{
 "openapi": "3.0.3",
 "info": {
  "title": "Singularis API",
  "version": "3.0",
  "description": "Singularis is unlimited computation. Bring us your hardest problems. Free agent key: 500 credits instantly (US, first 1000 agents). Docs: https://getsingularis.com/docs Results depend on your equipment. GPU optional for even greater results. Jobs run on your machine through the Singularis engine; this API issues keys, leases and signed receipts. More efficient computation for you and the environment.\n"
 },
 "servers": [
  {
   "url": "https://getsingularis.com/api/v1"
  }
 ],
 "components": {
  "securitySchemes": {
   "bearer": {
    "type": "http",
    "scheme": "bearer"
   }
  },
  "schemas": {
   "Error": {
    "type": "object",
    "properties": {
     "code": {
      "type": "string"
     },
     "detail": {
      "type": "string"
     }
    }
   }
  }
 },
 "security": [
  {
   "bearer": []
  }
 ],
 "paths": {
  "/health": {
   "get": {
    "security": [],
    "summary": "Service health and free agent slots",
    "responses": {
     "200": {
      "description": "ok"
     }
    }
   }
  },
  "/pricing": {
   "get": {
    "security": [],
    "summary": "Packs and pricing",
    "responses": {
     "200": {
      "description": "ok"
     }
    }
   }
  },
  "/agent/claim": {
   "post": {
    "security": [],
    "summary": "Free agent key, instant: 500 credits (US, first 1000 agents). Only country and agent_name needed.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "country",
         "agent_name"
        ],
        "properties": {
         "country": {
          "type": "string",
          "example": "US"
         },
         "agent_name": {
          "type": "string"
         },
         "post_url": {
          "type": "string"
         },
         "review": {
          "type": "string"
         },
         "prior_cloud_usd": {
          "type": "number"
         },
         "singularis_usd": {
          "type": "number"
         },
         "speedup": {
          "type": "number"
         },
         "hardware": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "api_key, shell_secret, credits"
     },
     "403": {
      "description": "us_only or agent_cap",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "409": {
      "description": "already_claimed"
     }
    }
   }
  },
  "/agent/results": {
   "post": {
    "summary": "Share your results and before-vs-after cost (optional, appreciated)",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "post_url": {
          "type": "string"
         },
         "review": {
          "type": "string"
         },
         "prior_cloud_usd": {
          "type": "number"
         },
         "singularis_usd": {
          "type": "number"
         },
         "speedup": {
          "type": "number"
         },
         "hardware": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "thanks"
     },
     "401": {
      "description": "unauthorized"
     }
    }
   }
  },
  "/usage": {
   "get": {
    "summary": "Credits remaining and usage",
    "responses": {
     "200": {
      "description": "ok"
     },
     "401": {
      "description": "unauthorized"
     }
    }
   }
  },
  "/lease": {
   "post": {
    "summary": "Reserve credits for one job that runs on your machine",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "kind",
         "input_sha256"
        ],
        "properties": {
         "kind": {
          "type": "string"
         },
         "input_sha256": {
          "type": "string"
         },
         "max_cpu_seconds": {
          "type": "number"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "lease + sig (or reuse result)"
     },
     "402": {
      "description": "credits used up"
     },
     "429": {
      "description": "rate limited"
     }
    }
   }
  },
  "/receipt": {
   "post": {
    "summary": "Settle a lease with a receipt signed with your shell_secret (HMAC-SHA256 of lease.id + result_digest + cpu_seconds)",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "lease",
         "sig",
         "result",
         "cpu_seconds",
         "receipt_sig"
        ],
        "properties": {
         "lease": {
          "type": "object"
         },
         "sig": {
          "type": "string"
         },
         "result": {},
         "result_digest": {
          "type": "string"
         },
         "cpu_seconds": {
          "type": "string"
         },
         "receipt_sig": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "signed usage receipt"
     },
     "400": {
      "description": "bad lease or receipt"
     },
     "409": {
      "description": "lease used or expired"
     }
    }
   }
  },
  "/fail": {
   "post": {
    "summary": "Report a failed local run; the reservation is released",
    "responses": {
     "200": {
      "description": "released"
     }
    }
   }
  },
  "/topup": {
   "post": {
    "summary": "Stripe checkout link for a pack",
    "responses": {
     "200": {
      "description": "checkout_url"
     }
    }
   }
  },
  "/keys": {
   "get": {
    "security": [],
    "summary": "Public keys: post-quantum session material, result-lock and receipt-signing public keys, engine payload hash",
    "responses": {
     "200": {
      "description": "pq, result_lock_x25519, receipt_ed25519, engine_payload_sha256"
     }
    }
   }
  },
  "/shell/bundle": {
   "get": {
    "summary": "Download your account's sealed shell bundle (application/gzip)",
    "responses": {
     "200": {
      "description": "singularis-shell-bundle.tar.gz"
     },
     "401": {
      "description": "unauthorized"
     },
     "404": {
      "description": "bundle not published yet"
     }
    }
   }
  },
  "/carry/register": {
   "get": {
    "summary": "Look up a registered Data Carry digest",
    "parameters": [
     {
      "name": "digest",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "digest, account, manifest, registered_ts"
     },
     "401": {
      "description": "unauthorized"
     },
     "404": {
      "description": "not_registered"
     }
    }
   },
   "post": {
    "summary": "Register a Data Carry digest with manifest metadata (digests only, payloads refused; 100 credits)",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "digest",
         "manifest"
        ],
        "properties": {
         "digest": {
          "type": "string"
         },
         "manifest": {
          "type": "object"
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "registered"
     },
     "400": {
      "description": "bad_digest, bad_manifest, digests_only or manifest_too_large"
     },
     "401": {
      "description": "unauthorized"
     },
     "402": {
      "description": "credit_limit: registration is 100 credits"
     }
    }
   }
  },
  "/signup": {
   "post": {
    "security": [],
    "summary": "Create an account for a vetted US organization (free tier: 100 credits)",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "verified_org_id",
         "country"
        ],
        "properties": {
         "verified_org_id": {
          "type": "string"
         },
         "country": {
          "type": "string",
          "example": "US"
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "api_key, account, shell_secret, credits"
     },
     "403": {
      "description": "verification_required"
     },
     "409": {
      "description": "already_claimed"
     }
    }
   }
  },
  "/pq/session": {
   "post": {
    "security": [],
    "summary": "Open a post-quantum session for sealed requests (hybrid X25519 + ML-KEM handshake)",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "x25519",
         "ml_kem_ct"
        ],
        "properties": {
         "x25519": {
          "type": "string"
         },
         "ml_kem_ct": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "sid, ttl (900 seconds)"
     },
     "400": {
      "description": "bad_pq_handshake"
     }
    }
   }
  },
  "/pq": {
   "post": {
    "security": [],
    "summary": "Send one sealed post-quantum envelope to an API route",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "sid",
         "n",
         "ct"
        ],
        "properties": {
         "sid": {
          "type": "string"
         },
         "n": {
          "type": "integer"
         },
         "ct": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "the sealed route's response"
     },
     "400": {
      "description": "pq_decrypt or pq_path"
     },
     "401": {
      "description": "pq_session: unknown, expired or replayed message"
     }
    }
   }
  }
 }
}