{"path":"lib/api-spec/openapi.yaml","size":8556,"locked":false,"binary":false,"truncated":false,"content":"openapi: 3.1.0\ninfo:\n  # Do not change the title, if the title changes, the import paths will be broken\n  title: Api\n  version: 0.1.0\n  description: Mappers Protocol API\nservers:\n  - url: /api\n    description: Base API path\ntags:\n  - name: health\n    description: Health operations\n  - name: jobs\n    description: Escrow job management\n  - name: stats\n    description: Dashboard statistics\n  - name: oracle\n    description: Oracle proxy\npaths:\n  /healthz:\n    get:\n      operationId: healthCheck\n      tags: [health]\n      summary: Health check\n      description: Returns server health status\n      responses:\n        \"200\":\n          description: Healthy\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/HealthStatus\"\n\n  /jobs:\n    get:\n      operationId: listJobs\n      tags: [jobs]\n      summary: List all jobs\n      description: Returns all registered escrow jobs\n      parameters:\n        - in: query\n          name: status\n          schema:\n            type: string\n            enum: [pending, completed, cancelled]\n          required: false\n        - in: query\n          name: clientPubkey\n          schema:\n            type: string\n          required: false\n      responses:\n        \"200\":\n          description: List of jobs\n          content:\n            application/json:\n              schema:\n                type: array\n                items:\n                  $ref: \"#/components/schemas/Job\"\n    post:\n      operationId: createJob\n      tags: [jobs]\n      summary: Register a job\n      description: Cache an on-chain job in the database after initialization\n      requestBody:\n        required: true\n        content:\n          application/json:\n            schema:\n              $ref: \"#/components/schemas/JobInput\"\n      responses:\n        \"201\":\n          description: Job created\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Job\"\n        \"400\":\n          description: Validation error\n\n  /jobs/{jobId}:\n    get:\n      operationId: getJob\n      tags: [jobs]\n      summary: Get a job by jobId\n      parameters:\n        - in: path\n          name: jobId\n          schema:\n            type: string\n          required: true\n      responses:\n        \"200\":\n          description: Job found\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Job\"\n        \"404\":\n          description: Not found\n    patch:\n      operationId: updateJob\n      tags: [jobs]\n      summary: Update job status or metadata\n      parameters:\n        - in: path\n          name: jobId\n          schema:\n            type: string\n          required: true\n      requestBody:\n        required: true\n        content:\n          application/json:\n            schema:\n              $ref: \"#/components/schemas/JobUpdate\"\n      responses:\n        \"200\":\n          description: Updated job\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/Job\"\n        \"404\":\n          description: Not found\n\n  /jobs/{jobId}/submit:\n    post:\n      operationId: submitDeliverable\n      tags: [jobs]\n      summary: Submit a deliverable for AI verification\n      description: Proxies the deliverable to the oracle for Gemini + Claude consensus\n      parameters:\n        - in: path\n          name: jobId\n          schema:\n            type: string\n          required: true\n      requestBody:\n        required: true\n        content:\n          application/json:\n            schema:\n              $ref: \"#/components/schemas/DeliverableInput\"\n      responses:\n        \"200\":\n          description: Verification result\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/SubmitResult\"\n        \"400\":\n          description: Validation error\n        \"404\":\n          description: Job not found\n        \"503\":\n          description: Oracle unavailable\n\n  /stats:\n    get:\n      operationId: getStats\n      tags: [stats]\n      summary: Dashboard statistics\n      description: Returns counts of jobs by status and total escrowed amount\n      responses:\n        \"200\":\n          description: Dashboard stats\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/DashboardStats\"\n\n  /oracle/health:\n    get:\n      operationId: getOracleHealth\n      tags: [oracle]\n      summary: Oracle health proxy\n      description: Returns the oracle middleware health and pending job count\n      responses:\n        \"200\":\n          description: Oracle healthy\n          content:\n            application/json:\n              schema:\n                $ref: \"#/components/schemas/OracleHealth\"\n        \"503\":\n          description: Oracle unavailable\n\ncomponents:\n  schemas:\n    HealthStatus:\n      type: object\n      properties:\n        status:\n          type: string\n      required:\n        - status\n\n    Job:\n      type: object\n      properties:\n        id:\n          type: integer\n        jobId:\n          type: string\n        clientPubkey:\n          type: string\n        freelancerPubkey:\n          type: string\n        oraclePubkey:\n          type: string\n        amountLamports:\n          type: string\n          description: Amount in lamports as string (u64 safe)\n        status:\n          type: string\n          enum: [pending, completed, cancelled]\n        description:\n          type: [\"string\", \"null\"]\n        acceptanceCriteria:\n          type: [\"string\", \"null\"]\n          description: JSON-encoded array of criteria strings\n        txSig:\n          type: [\"string\", \"null\"]\n          description: Most recent transaction signature\n        createdAt:\n          type: string\n          format: date-time\n        updatedAt:\n          type: string\n          format: date-time\n      required:\n        - id\n        - jobId\n        - clientPubkey\n        - freelancerPubkey\n        - oraclePubkey\n        - amountLamports\n        - status\n        - description\n        - acceptanceCriteria\n        - txSig\n        - createdAt\n        - updatedAt\n\n    JobInput:\n      type: object\n      properties:\n        jobId:\n          type: string\n          maxLength: 32\n        clientPubkey:\n          type: string\n        freelancerPubkey:\n          type: string\n        oraclePubkey:\n          type: string\n        amountLamports:\n          type: string\n        description:\n          type: string\n        acceptanceCriteria:\n          type: array\n          items:\n            type: string\n      required:\n        - jobId\n        - clientPubkey\n        - freelancerPubkey\n        - oraclePubkey\n        - amountLamports\n\n    JobUpdate:\n      type: object\n      properties:\n        status:\n          type: string\n          enum: [pending, completed, cancelled]\n        txSig:\n          type: string\n        description:\n          type: string\n\n    DeliverableInput:\n      type: object\n      properties:\n        description:\n          type: string\n        acceptanceCriteria:\n          type: array\n          items:\n            type: string\n        deliverable:\n          type: string\n        deliverableType:\n          type: string\n          enum: [url, ipfs, text, json]\n      required:\n        - description\n        - acceptanceCriteria\n        - deliverable\n        - deliverableType\n\n    SubmitResult:\n      type: object\n      properties:\n        success:\n          type: boolean\n        jobId:\n          type: string\n        outcome:\n          type: [\"string\", \"null\"]\n          enum: [RELEASE, REFUND, ESCALATE, null]\n        txSig:\n          type: [\"string\", \"null\"]\n        error:\n          type: [\"string\", \"null\"]\n      required:\n        - success\n        - jobId\n        - outcome\n        - txSig\n        - error\n\n    DashboardStats:\n      type: object\n      properties:\n        total:\n          type: integer\n        pending:\n          type: integer\n        completed:\n          type: integer\n        cancelled:\n          type: integer\n        totalEscrowedLamports:\n          type: string\n          description: Sum of pending escrow amounts as string\n      required:\n        - total\n        - pending\n        - completed\n        - cancelled\n        - totalEscrowedLamports\n\n    OracleHealth:\n      type: object\n      properties:\n        status:\n          type: string\n        pendingJobs:\n          type: integer\n        timestamp:\n          type: string\n      required:\n        - status\n        - pendingJobs\n        - timestamp\n"}