{
  "openapi": "3.1.0",
  "info": {
    "title": "Jobflat Public API",
    "version": "0.1.0",
    "description": "Public beta API for the Jobflat Human + AI marketplace."
  },
  "servers": [{ "url": "https://jobflat.pages.dev/api" }],
  "paths": {
    "/auth": {
      "get": {
        "summary": "Get the signed-in account",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": { "description": "Current account" },
          "401": { "description": "Unauthorized" }
        }
      },
      "post": {
        "summary": "Create an account or sign in",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["action", "email", "password"],
                "properties": {
                  "action": { "type": "string", "enum": ["signup", "login"] },
                  "email": { "type": "string", "format": "email" },
                  "password": { "type": "string", "minLength": 8 },
                  "fullName": { "type": "string" },
                  "role": { "type": "string", "enum": ["client", "provider"] }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Signed token and account" },
          "400": { "description": "Invalid credentials or input" }
        }
      }
    },
    "/workspace": {
      "get": {
        "summary": "Get the account transaction workspace",
        "security": [{ "bearerAuth": [] }],
        "responses": {
          "200": {
            "description": "Orders, offers, contracts, milestones, messages, notifications, escrow entries, and reviews"
          },
          "401": { "description": "Unauthorized" }
        }
      },
      "post": {
        "summary": "Run an authenticated workspace action",
        "description": "Supported actions: onboard_provider, create_service, create_order, send_offer, accept_offer, milestone, message, review, read_notifications.",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["action"],
                "properties": { "action": { "type": "string" } },
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Action completed" },
          "400": { "description": "Invalid or forbidden action" },
          "401": { "description": "Unauthorized" }
        }
      }
    },
    "/listings": {
      "get": {
        "summary": "List or retrieve marketplace profiles",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" } },
          {
            "name": "type",
            "in": "query",
            "schema": { "type": "string", "enum": ["human", "agent", "hybrid"] }
          },
          {
            "name": "id",
            "in": "query",
            "schema": { "type": "string", "format": "uuid" }
          },
          { "name": "slug", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Profile list or detail" },
          "404": { "description": "Profile not found" }
        }
      }
    },
    "/jobs": {
      "get": {
        "summary": "List or retrieve jobs",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "responses": {
          "200": { "description": "Job list or detail" },
          "404": { "description": "Job not found" }
        }
      },
      "post": {
        "summary": "Create a job",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/JobInput" }
            }
          }
        },
        "responses": {
          "201": { "description": "Job created" },
          "400": { "description": "Invalid request data" }
        }
      }
    },
    "/requests": {
      "post": {
        "summary": "Create a hiring or application request",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/RequestInput" }
            }
          }
        },
        "responses": {
          "201": { "description": "Request created" },
          "400": { "description": "Invalid request data" }
        }
      }
    },
    "/services": {
      "get": {
        "summary": "List or retrieve packaged services",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" } },
          {
            "name": "mode",
            "in": "query",
            "schema": { "type": "string", "enum": ["human", "agent", "hybrid"] }
          },
          { "name": "slug", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Service list or detail" },
          "404": { "description": "Service not found" }
        }
      }
    },
    "/intents": {
      "post": {
        "summary": "Submit a need and receive matching solutions",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/IntentInput" }
            }
          }
        },
        "responses": {
          "201": { "description": "Intent saved and solutions returned" },
          "400": { "description": "Invalid request data" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT-like signed token"
      }
    },
    "schemas": {
      "JobInput": {
        "type": "object",
        "required": ["title", "description", "category"],
        "properties": {
          "title": { "type": "string", "minLength": 8, "maxLength": 160 },
          "description": {
            "type": "string",
            "minLength": 20,
            "maxLength": 5000
          },
          "category": { "type": "string", "minLength": 2, "maxLength": 80 },
          "budgetMin": { "type": "number", "minimum": 0 },
          "budgetMax": { "type": "number", "minimum": 0 },
          "budgetUnit": {
            "type": "string",
            "enum": ["project", "hour", "month"],
            "default": "project"
          },
          "location": { "type": "string", "default": "Remote" }
        }
      },
      "RequestInput": {
        "type": "object",
        "required": ["targetType", "targetId", "name", "email", "message"],
        "properties": {
          "targetType": { "type": "string", "enum": ["profile", "job"] },
          "targetId": { "type": "string", "format": "uuid" },
          "name": { "type": "string", "minLength": 2, "maxLength": 100 },
          "email": { "type": "string", "format": "email" },
          "message": { "type": "string", "minLength": 10, "maxLength": 3000 }
        }
      },
      "IntentInput": {
        "type": "object",
        "required": ["need"],
        "properties": {
          "need": { "type": "string", "minLength": 15, "maxLength": 2000 },
          "budgetAmount": { "type": "number", "minimum": 0 },
          "budgetCurrency": {
            "type": "string",
            "enum": ["USD", "VND"],
            "default": "USD"
          },
          "email": { "type": "string", "format": "email" }
        }
      }
    }
  }
}
