{
  "openapi": "3.1.0",
  "info": {
    "title": "NI API",
    "description": "Natural Intelligence — human judgment as a service. Evaluate AI outputs, ask questions, hire workers, run votes, and verify content.",
    "version": "1.0.0",
    "contact": { "url": "https://ni.dev" }
  },
  "servers": [
    { "url": "https://ni.dev/api", "description": "Production" },
    { "url": "http://localhost:3000/api", "description": "Development" }
  ],
  "security": [{ "apiKey": [] }],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key from /api/keys"
      }
    },
    "schemas": {
      "Pair": {
        "type": "object",
        "required": ["prompt", "response_a", "response_b"],
        "properties": {
          "prompt": { "type": "string" },
          "response_a": { "type": "string" },
          "response_b": { "type": "string" },
          "image_a": { "type": "string" },
          "image_b": { "type": "string" },
          "quality_check": { "type": "boolean" },
          "known_answer": { "type": "string", "enum": ["a", "b"] }
        }
      },
      "SkillLevel": { "type": "string", "enum": ["beginner", "skilled", "expert"], "default": "beginner" },
      "VerificationType": { "type": "string", "enum": ["deepfake", "fact_check", "oracle"] }
    }
  },
  "paths": {
    "/tasks/batch": {
      "post": {
        "operationId": "createBatch",
        "summary": "Submit evaluation tasks",
        "description": "Create a batch of A/B comparisons, reviews, or labeling tasks for human evaluation.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["pairs"],
                "properties": {
                  "type": { "type": "string", "enum": ["preference_ranking", "single_review", "labeling"], "default": "preference_ranking" },
                  "domain": { "type": "string", "default": "general", "description": "e.g. general, coding, math, safety, ui_design" },
                  "pay_per_task_cents": { "type": "integer", "default": 25, "description": "25=beginner, 50=skilled, 100=expert" },
                  "workers_per_task": { "type": "integer", "default": 3 },
                  "min_tier": { "type": "string", "default": "phone" },
                  "min_skill_level": { "$ref": "#/components/schemas/SkillLevel" },
                  "model_a": { "type": "string" },
                  "model_b": { "type": "string" },
                  "pairs": { "type": "array", "items": { "$ref": "#/components/schemas/Pair" }, "maxItems": 10000 }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Batch created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "batch_id": { "type": "string" },
                    "tasks_created": { "type": "integer" },
                    "quality_checks": { "type": "integer" },
                    "workers_per_task": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "batchStatus",
        "summary": "Get batch status and results",
        "parameters": [{ "name": "id", "in": "query", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": {
            "description": "Batch status with results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "batch_id": { "type": "string" },
                    "status": { "type": "string" },
                    "stats": {
                      "type": "object",
                      "properties": {
                        "total": { "type": "integer" },
                        "completed": { "type": "integer" },
                        "pending": { "type": "integer" }
                      }
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "prompt": { "type": "string" },
                          "result": { "type": "string" },
                          "confidence": { "type": "number" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/polls": {
      "post": {
        "operationId": "createPoll",
        "summary": "Create a poll, survey, or expert question",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["title", "questions"],
                "properties": {
                  "title": { "type": "string" },
                  "description": { "type": "string" },
                  "mode": { "type": "string", "enum": ["vote", "survey", "oracle"], "default": "vote" },
                  "domain": { "type": "string", "default": "general" },
                  "min_skill_level": { "$ref": "#/components/schemas/SkillLevel" },
                  "pay_per_response_cents": { "type": "integer", "default": 10 },
                  "target_responses": { "type": "integer", "default": 50 },
                  "target_demographics": { "type": "string", "description": "JSON demographics filter" },
                  "questions": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": ["question"],
                      "properties": {
                        "question": { "type": "string" },
                        "question_type": { "type": "string", "enum": ["choice", "text", "yes_no", "scale"], "default": "choice" },
                        "options": { "type": "array", "items": { "type": "string" } }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Poll created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "poll_id": { "type": "string" },
                    "questions_created": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "getPollResults",
        "summary": "Get poll results",
        "parameters": [
          { "name": "id", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "results", "in": "query", "schema": { "type": "boolean", "default": true } }
        ],
        "responses": {
          "200": {
            "description": "Poll results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "poll_id": { "type": "string" },
                    "title": { "type": "string" },
                    "mode": { "type": "string" },
                    "status": { "type": "string" },
                    "total_respondents": { "type": "integer" },
                    "questions": { "type": "array", "items": { "type": "object" } }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/bounties": {
      "post": {
        "operationId": "createBounty",
        "summary": "Post a one-off task for a worker to claim",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["title", "description"],
                "properties": {
                  "title": { "type": "string" },
                  "description": { "type": "string" },
                  "domain": { "type": "string", "default": "general" },
                  "pay_cents": { "type": "integer", "default": 500 },
                  "min_skill_level": { "$ref": "#/components/schemas/SkillLevel" },
                  "min_tier": { "type": "string", "default": "phone" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Bounty created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "bounty_id": { "type": "string" },
                    "status": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/verify": {
      "post": {
        "operationId": "createVerification",
        "summary": "Submit content for human verification",
        "description": "Deepfake detection, fact checking, or oracle (open question).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["type", "content"],
                "properties": {
                  "type": { "$ref": "#/components/schemas/VerificationType" },
                  "content": { "type": "string", "description": "Text, URL, or claim to verify" },
                  "context": { "type": "string" },
                  "skill_level": { "$ref": "#/components/schemas/SkillLevel" },
                  "votes": { "type": "integer", "default": 5, "description": "Number of reviewers" },
                  "tier": { "type": "string", "enum": ["free", "paid"], "default": "paid" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Verification created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verification_id": { "type": "string" },
                    "public_id": { "type": "string" },
                    "public_url": { "type": "string" },
                    "status": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/verify/{public_id}": {
      "get": {
        "operationId": "getVerificationStatus",
        "summary": "Check verification result",
        "parameters": [{ "name": "public_id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": {
            "description": "Verification status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "type": { "type": "string" },
                    "status": { "type": "string" },
                    "result": { "type": "string" },
                    "confidence": { "type": "number" },
                    "votes_received": { "type": "integer" },
                    "votes_needed": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/elections": {
      "post": {
        "operationId": "createElection",
        "summary": "Create a vote or election",
        "description": "One-person-one-vote with Orb verification, time-locked results.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["title", "options", "closes_at"],
                "properties": {
                  "title": { "type": "string" },
                  "description": { "type": "string" },
                  "options": { "type": "array", "items": { "type": "string" } },
                  "election_type": { "type": "string", "enum": ["simple", "approval", "ranked_choice"], "default": "simple" },
                  "access_mode": { "type": "string", "enum": ["public", "code", "invite_list"], "default": "public" },
                  "access_code": { "type": "string" },
                  "invite_list": { "type": "array", "items": { "type": "string" } },
                  "min_verification": { "type": "string", "default": "world_id_orb" },
                  "opens_at": { "type": "string", "format": "date-time" },
                  "closes_at": { "type": "string", "format": "date-time" },
                  "pay_cents": { "type": "integer", "default": 500 }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Election created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "election_id": { "type": "string" },
                    "status": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "getElectionResults",
        "summary": "Get election results",
        "parameters": [{ "name": "id", "in": "query", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Election results" }
        }
      }
    },
    "/sponsored": {
      "post": {
        "operationId": "createSponsored",
        "summary": "Create sponsored content for verified human attention",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["title", "content_type"],
                "properties": {
                  "title": { "type": "string" },
                  "description": { "type": "string" },
                  "content_type": { "type": "string", "enum": ["text", "image", "video", "link"] },
                  "content_url": { "type": "string" },
                  "pay_per_view_cents": { "type": "integer", "default": 5 },
                  "target_views": { "type": "integer", "default": 1000 },
                  "target_demographics": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Sponsored content created" }
        }
      }
    },
    "/leaderboard": {
      "get": {
        "operationId": "getLeaderboard",
        "summary": "Get AI model leaderboard rankings",
        "parameters": [{ "name": "domain", "in": "query", "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Leaderboard data" }
        }
      }
    }
  }
}