{ "openapi": "3.0.3", "info": { "title": "Askuno API", "version": "0.1.0", "description": "Askuno is an OpenAI-compatible LLM gateway API for agents and CLIs. Developers can start with covered API credits, budget credits per task, browse bounty candidates, and use registered Askuno-managed bounty work to pursue third-party bounty payouts. OpenClaw is the intended backend route, with fallback providers available where configured. Paid credit top-ups are deprecated; Askuno's active release model is bounty-backed work. When call-proof signing is configured, responses can include an Ed25519 call-proof for independent verification.", "contact": { "name": "Askuno Docs", "url": "https://askuno.app/docs" } }, "servers": [ { "url": "https://askuno.app", "description": "Production" } ], "security": [], "components": { "securitySchemes": { "bearerApiKey": { "type": "http", "scheme": "bearer", "description": "A long-lived API key issued by `POST /api/keys/issue`. Keys start with `ak_` followed by 64 hex characters (67 characters total, 256-bit random entropy). Only a SHA-256 hash is stored server-side — the plaintext is returned exactly once at creation and cannot be retrieved again. Pass in the `Authorization` header: `Bearer ak_…`." }, "sessionAuth": { "type": "http", "scheme": "bearer", "description": "A short-lived Supabase JWT obtained after signing in at `/signin`. Suitable for browser-side calls. Pass in the `Authorization` header: `Bearer `. API keys are preferred for server-to-server use." }, "cronSecret": { "type": "http", "scheme": "bearer", "description": "Internal Vercel Cron bearer value automatically sent from the `CRON_SECRET` environment variable. This is not a user token and must never be exposed client-side." }, "apiToken": { "type": "apiKey", "in": "header", "name": "x-askuno-api-token", "description": "Accountless or per-instance API token. Trial tokens start with `askuno_sk_`, are returned once by `POST /api/trials/start`, and enforce request and credit limits before a full account is created." }, "weaveSignature": { "type": "apiKey", "in": "header", "name": "x-weave-signature", "description": "Hex-encoded HMAC-SHA256 signature for the server-to-server `/api/credits/grant` endpoint. Computed as `HMAC-SHA256(WEAVE_RUNTIME_GRANT_HMAC_KEY, \"${timestamp}.${rawBody}\")` (Stripe-style). Must be sent together with the `x-weave-timestamp` header (`weaveTimestamp` security scheme)." }, "weaveTimestamp": { "type": "apiKey", "in": "header", "name": "x-weave-timestamp", "description": "Unix timestamp in seconds (string) sent alongside `x-weave-signature`. Requests with a timestamp older than 300 seconds are rejected to prevent replay attacks." } }, "schemas": { "ChatRequest": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "The user message to send to the LLM.", "example": "Explain zero-knowledge proofs in two paragraphs." }, "modelId": { "type": "string", "description": "Optional model ID. Defaults to `qwen3:8b` (1 credit/call). See /api/config for the full model list.", "example": "Qwen3-Coder-30B-A3B-Instruct" }, "threadId": { "type": "string", "description": "Optional existing thread ID to continue a conversation.", "example": "thread_01hwz3r9k8fxbvcnmqsd7jtpe6" }, "revenueModelId": { "type": "string", "description": "Optional revenue model override. Defaults to `standard-v0`.", "example": "standard-v0" } } }, "ChatResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "answer": { "type": "string", "description": "The assistant's reply.", "example": "Zero-knowledge proofs allow one party to prove knowledge of a value without revealing it..." }, "threadId": { "type": "string", "example": "thread_01hwz3r9k8fxbvcnmqsd7jtpe6" }, "modelId": { "type": "string", "example": "qwen3:8b" }, "creditsSpent": { "type": "integer", "example": 1 }, "weave_call_proof": { "type": "string", "nullable": true, "description": "X-Weave-Call-Proof header value when call-proof signing is configured and attached; null otherwise.", "example": "v1.42.1747000000.ab12cd34ef56ab78.qwen3:8b.deadbeefabc123.MEUCIQDabc123" } } }, "Mission": { "type": "object", "properties": { "id": { "type": "string", "example": "legacy-review-001" }, "title": { "type": "string", "example": "Review a submitted PR" }, "scope": { "type": "string", "example": "Verify a submitted PR against the registered work requirements." }, "repo": { "type": "string", "example": "example-org/example-repo" }, "credit_reward": { "type": "integer", "example": 500 }, "status": { "type": "string", "enum": [ "open", "claimed", "completed" ], "example": "open" }, "acceptance_criteria": { "type": "string", "example": "All existing tests pass; new test added." } } }, "Claim": { "type": "object", "properties": { "mission_id": { "type": "string", "example": "legacy-review-001" }, "status": { "type": "string", "enum": [ "claimed", "submitted", "approved", "rejected" ], "example": "claimed" }, "claimed_at": { "type": "string", "format": "date-time", "example": "2026-05-11T10:00:00Z" }, "github_pr_url": { "type": "string", "nullable": true, "example": "https://github.com/example-org/example-repo/pull/42" }, "credit_reward": { "type": "integer", "example": 500 } } }, "CreditGrant": { "type": "object", "required": [ "user_id", "credits", "source", "mission_id" ], "properties": { "user_id": { "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "credits": { "type": "integer", "minimum": 1, "maximum": 1000, "example": 500 }, "source": { "type": "string", "example": "bounty" }, "mission_id": { "type": "string", "description": "Work ID. Required when source is `bounty` or `mission`. Also serves as the idempotency key — duplicate POSTs with the same (source, mission_id) return the original grant.", "example": "bounty-001" }, "evidence_path": { "type": "string", "nullable": true, "description": "Optional path to verification evidence (e.g. PR URL or artifact path).", "example": "https://github.com/example-org/example-repo/pull/42" } } }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "k1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "last4": { "type": "string", "example": "ab3f" }, "name": { "type": "string", "nullable": true, "example": "prod-server" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-05-01T09:00:00Z" }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true, "example": null }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-05-10T14:23:00Z" } } }, "MeResponse": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "balance": { "type": "integer", "description": "Current credit balance.", "example": 480 }, "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "recent_debits": { "type": "array", "items": { "type": "object", "properties": { "credits": { "type": "integer", "example": 1 }, "source": { "type": "string", "example": "chat_call" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-05-10T14:23:00Z" } } } }, "claimed_missions": { "type": "array", "items": { "$ref": "#/components/schemas/Claim" } } } }, "CallProofPublicKey": { "type": "object", "properties": { "scheme": { "type": "string", "example": "weave-call-proof/v1" }, "algorithm": { "type": "string", "example": "Ed25519" }, "public_key": { "type": "string", "nullable": true, "description": "Base64 SPKI DER Ed25519 public key, or null when call-proof signing is not configured.", "example": "MCowBQYDK2VwAyEA..." }, "header_name": { "type": "string", "example": "X-Weave-Call-Proof" }, "canonical_format": { "type": "string", "example": "weave-call-proof|v1|||||" }, "timestamp_window_seconds": { "type": "integer", "example": 300 }, "documentation": { "type": "string" } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "Machine-readable error code.", "example": "auth_required" }, "message": { "type": "string", "description": "Optional human-readable explanation.", "example": "No valid session or API key found." } } } } }, "paths": { "/api/health": { "get": { "operationId": "getHealth", "summary": "Service health", "description": "Returns the liveness status of the Askuno runtime, the active LLM gateway, and configured auth provider. No authentication required.", "tags": [ "System" ], "security": [], "responses": { "200": { "description": "Runtime is healthy.", "content": { "application/json": { "example": { "ok": true, "service": "askuno", "modelMode": "blueclaw", "llmGateway": { "configured": true, "provider": "blueclaw" }, "models": [ { "id": "qwen3:8b", "label": "Fast", "tier": "cheap" } ], "auth": { "configured": true, "provider": "supabase" } } } } } } } }, "/api/config": { "get": { "operationId": "getConfig", "summary": "Public runtime config", "description": "Returns public-safe runtime configuration including available models, auth settings, pricing, and feature flags. No authentication required. Secrets are never exposed.", "tags": [ "System" ], "security": [], "responses": { "200": { "description": "Config payload.", "content": { "application/json": { "example": { "appName": "Askuno", "signup_grant_credits": 500, "credit_cost_per_chat_call": 1, "docs_url": "/docs", "models": [ { "id": "qwen3:8b", "label": "Fast", "provider": "Qwen", "tier": "cheap", "credit_cost": 1 }, { "id": "gemma3:4b", "label": "Gemma 4B", "provider": "Gemma", "tier": "fast", "credit_cost": 2 }, { "id": "Qwen3-Coder-30B-A3B-Instruct", "label": "Coder", "provider": "Qwen", "tier": "developer", "credit_cost": 4 }, { "id": "gemma4:26b", "label": "Gemma 26B", "provider": "Gemma", "tier": "deep", "credit_cost": 4 }, { "id": "Qwen3.6-27B", "label": "Qwen 27B", "provider": "Qwen", "tier": "reasoning", "credit_cost": 4 } ], "missions_repo": "its-DeFine/askuno-registry", "bounty_model": { "active_source": "algora", "askuno_managed_default": true, "external_claims": "prepared_by_askuno_only_until_owner_approval" }, "credit_funding": { "activeRevenueModel": "bounty_backed", "paidCreditTopUps": "deprecated", "next_url": "/missions.html" } } } } } } } }, "/api/missions": { "get": { "operationId": "listMissions", "summary": "List active missions", "description": "Returns the current list of open engineering missions. Each mission has a credit reward, acceptance criteria, and a GitHub repo link. No authentication required.", "tags": [ "Missions" ], "security": [], "responses": { "200": { "description": "Mission list.", "content": { "application/json": { "example": { "missions": [ { "id": "legacy-review-001", "title": "Review a submitted PR", "scope": "Verify a submitted PR against the registered work requirements.", "repo": "example-org/example-repo", "credit_reward": 500, "status": "open" } ] } } } } } } }, "/api/bounties/candidates": { "get": { "operationId": "listBountyCandidates", "summary": "List bounty candidates", "description": "Returns the neutral multi-source bounty catalog visible to Askuno. Candidate results are read-only and do not register work, claim external bounties, submit PRs, move money, or change live credit authority.", "tags": [ "Bounties" ], "security": [], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 40 } } ], "responses": { "200": { "description": "Bounty candidate catalog.", "content": { "application/json": { "example": { "ok": true, "schema": "askuno-bounty-candidate-catalog/v0.1", "auto_register_candidates": false, "bounties": [ { "inventory_id": "github-example-org-example-repo-42", "title": "Fix a tagged bounty issue", "target_repo": "example-org/example-repo", "issue_url": "https://github.com/example-org/example-repo/issues/42", "amount_label": "$500", "askuno_management": { "registration_required": true } } ] } } } } } } }, "/api/admin/bounties/candidates/register": { "post": { "operationId": "registerBountyCandidate", "summary": "Preview or register a bounty candidate for Askuno-managed work", "description": "Operator-only workflow for turning a selected multi-source bounty candidate into registered Askuno-managed bounty work. The route dry-runs by default. Registration writes only Askuno internal bounty state when dry_run=false and still performs no GitHub, external bounty, payment, banking, or live credit-authority action.", "tags": [ "Bounties" ], "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "dry_run": true, "candidate_id": "github_bounty_radar:github-radar-example-org-example-repo-42", "source": "github" } } } }, "responses": { "200": { "description": "Registration preview or idempotent existing registration.", "content": { "application/json": { "example": { "ok": true, "schema": "askuno-bounty-candidate-registration/v0.1", "mode": "dry_run_registration_preview", "dry_run": true, "state_write_performed": false, "external_actions_performed": false, "selected_candidate": { "bounty_id": "github-radar-example-org-example-repo-42", "target_repo": "example-org/example-repo", "issue_number": 42 }, "user_flow_after_registration": { "available_url": "/api/bounties/algora/available", "start_url": "/api/bounties/algora/github-radar-example-org-example-repo-42/start" }, "authority": { "github_write": false, "external_bounty_write": false, "payment_action": false, "live_credit_authority_change": false } } } } }, "201": { "description": "Candidate registered into Askuno internal bounty state.", "content": { "application/json": { "example": { "ok": true, "mode": "operator_registration", "dry_run": false, "state_write_performed": true, "registration": { "source": "github_bounty_radar", "bounty_id": "github-radar-example-org-example-repo-42", "work_mode": "askuno_managed" } } } } } } } }, "/api/bounties/algora": { "get": { "operationId": "listAlgoraBounties", "summary": "List detected Algora bounties", "description": "Reads configured public Algora org bounty feeds and normalizes them for Askuno. This endpoint does not claim bounties, create payments, submit PRs, or call authenticated Algora APIs.", "tags": [ "Bounties" ], "security": [], "parameters": [ { "name": "org", "in": "query", "required": false, "schema": { "type": "string" }, "example": "example-org" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "example": 25 } ], "responses": { "200": { "description": "Detected Algora bounties.", "content": { "application/json": { "example": { "ok": true, "source": "algora", "configured": true, "bounties": [ { "source": "algora", "bounty_id": "bty_algora_123", "mission_id": "algora-bty_algora_123", "target_repo": "example-org/example-repo", "issue_url": "https://github.com/example-org/example-repo/issues/42", "amount_usd": 1500, "status": "active" } ] } } } } } } }, "/api/bounties/algora/workflow": { "get": { "operationId": "getAlgoraBountyWorkflow", "summary": "Get the Askuno-managed Algora workflow packet", "description": "Returns one machine-readable contract for agents and Hermes operators: user steps, operator steps, free bounty-work cap, payout recipient boundary, status map, private verifier, and owner-gated live execution point. This endpoint is read-only and exposes no credentials or payment receiver references.", "tags": [ "Bounties" ], "security": [], "responses": { "200": { "description": "Askuno-managed Algora workflow packet.", "content": { "application/json": { "example": { "ok": true, "schema": "askuno-algora-workflow/v0.1", "source": "algora", "mode": "askuno_managed", "policy": { "askuno_managed_default": true, "user_free_cap": { "mode": "bounty_backed_free_cap", "credits": 25000, "requestsPerDay": 2500 }, "payment_receiver": { "recipient": "askuno", "configured": false, "receiverRefExposed": false }, "future_user_payout_boundary": "future_internal_banking_or_wise_flow" }, "endpoints": { "available": "GET /api/bounties/algora/available", "mission_packet": "GET /api/bounties/algora/{bounty_id}/mission-packet", "claim": "POST /api/bounties/algora/{bounty_id}/claim", "complete": "POST /api/bounties/algora/{bounty_id}/complete", "hermes_tasks": "GET /api/admin/bounties/algora/hermes-tasks", "hermes_runtime_tick": "POST /api/admin/bounties/algora/hermes-runtime-tick", "hermes_advance": "POST /api/admin/bounties/algora/hermes-advance", "go_live_plan": "GET /api/admin/bounties/algora/go-live-plan", "live_readiness": "GET /api/admin/bounties/algora/live-readiness?claim_id={claim_id}" }, "authority": { "workflow_read_external_actions_performed": false, "live_execution_owner_approval_required": true, "payment_action": false, "banking_action": false, "secrets_included": false } } } } } } } }, "/api/admin/bounties/algora/poll": { "post": { "operationId": "pollAlgoraBounties", "summary": "Poll Algora and optionally import bounty work", "description": "Operator-only Askuno runtime detector. It reads configured public Algora bounty feeds, defaults to dry_run=true, and reports exact import actions. When explicitly called with dry_run=false it registers importable bounties into Askuno's own registry. It performs no GitHub, Algora claim, payment, banking, or live credit authority writes.", "tags": [ "Bounties" ], "security": [ { "sessionAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "example": { "dry_run": true, "limit": 25, "max_imports": 10 } } } }, "responses": { "200": { "description": "Poll result with exact dry-run or import actions.", "content": { "application/json": { "example": { "ok": true, "source": "algora", "mode": "askuno_managed_poll", "dry_run": true, "detected_count": 1, "importable_count": 1, "imported_count": 0, "actions": [ { "action": "would_register", "bounty_id": "bty_algora_123", "target_repo": "example-org/example-repo", "issue_url": "https://github.com/example-org/example-repo/issues/42", "amount_usd": 1500, "external_actions_performed": false } ], "external_actions_performed": false } } } }, "503": { "description": "Production-like import was requested without durable Askuno bounty state." } } } }, "/api/admin/bounties/algora/candidate-routing": { "get": { "operationId": "getAlgoraCandidateRouting", "summary": "Preview Askuno routing for live detected Algora bounties", "description": "Operator-only read-only endpoint that converts detected Algora bounty candidates into Askuno registration previews. Each candidate includes the future register endpoint, mission packet URL, start/claim/status/complete URLs, bounty-work free cap, required /claim #issue command, completion contract, Askuno payout recipient, and no-write authority flags. It performs no registration, GitHub write, Algora write, payment, banking, Wise, or live credit authority action.", "tags": [ "Bounties" ], "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "org", "in": "query", "required": false, "schema": { "type": "string" }, "example": "projectdiscovery" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 25 }, "example": 2 }, { "name": "bounty_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "public-board-projectdiscovery-projectdiscovery-nuclei-6674" } ], "responses": { "200": { "description": "Read-only candidate routing packets.", "content": { "application/json": { "example": { "ok": true, "schema": "askuno-algora-candidate-routing-list/v0.1", "mode": "operator_read_only_candidate_routing", "count": 1, "candidates": [ { "schema": "askuno-algora-live-candidate-routing-packet/v0.1", "mode": "read_only_registration_preview", "detection": { "bounty_id": "public-board-projectdiscovery-projectdiscovery-nuclei-6674", "target_repo": "projectdiscovery/nuclei", "issue_number": 6674, "issue_url": "https://github.com/projectdiscovery/nuclei/issues/6674", "amount_usd": 100, "detection_method": "public_board_html" }, "registration_preview": { "would_register": true, "state_write_performed": false, "register_endpoint": "POST /api/bounties/algora/register", "work_mode": "askuno_managed" }, "user_routing_preview": { "mission_packet_url": "/api/bounties/algora/public-board-projectdiscovery-projectdiscovery-nuclei-6674/mission-packet", "start_url": "/api/bounties/algora/public-board-projectdiscovery-projectdiscovery-nuclei-6674/start", "claim_url": "/api/bounties/algora/public-board-projectdiscovery-projectdiscovery-nuclei-6674/claim", "status_url": "/api/bounties/algora/public-board-projectdiscovery-projectdiscovery-nuclei-6674/status", "complete_url": "/api/bounties/algora/public-board-projectdiscovery-projectdiscovery-nuclei-6674/complete", "free_cap": { "mode": "bounty_backed_free_cap", "credits": 25000, "requires_registered_claimable_bounty": true }, "issue": { "algora_claim_command_hint": "/claim #6674" } }, "economics": { "payout_recipient": { "recipient": "askuno", "receiverRefExposed": false } }, "authority": { "external_writes_performed": false, "local_state_write_performed": false, "github_write": false, "algora_write": false, "payment_action": false, "banking_action": false, "wise_action": false, "live_credit_authority_change": false, "secrets_included": false } } ], "external_calls": { "methods": [ "GET" ], "writes": 0 }, "authority": { "external_writes_performed": 0, "local_state_write_performed": false, "receiver_ref_exposed": false } } } } } } } }, "/api/admin/bounties/algora/readiness": { "get": { "operationId": "getAlgoraRuntimeReadiness", "summary": "Inspect Askuno Algora runtime readiness", "description": "Operator-only preflight contract for the Askuno-managed Algora lane. It reports detector config, optional read-only public feed probe status, durable state, bounty free cap, assignment safety, Askuno payout receiver readiness, solver identity readiness, GitHub/Algora credential presence booleans, and live-execution blockers without returning credential values or receiver references.", "tags": [ "Bounties" ], "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "check_public_feed", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": true } ], "responses": { "200": { "description": "Secret-free runtime readiness contract.", "content": { "application/json": { "example": { "ok": true, "schema": "askuno-algora-runtime-readiness/v0.1", "mode": "askuno_managed_preflight", "gates": { "detector_configured": true, "durable_store_configured": true, "payment_receiver": { "recipient": "askuno", "receiverRefConfigured": true, "receiverRefExposed": false }, "solver_identity": { "configured": true, "loginExposed": false }, "github_write_credentials_configured": false, "credential_values_exposed": false }, "capabilities": { "user_bounty_assignment_ready": true, "askuno_payment_receipt_ready": true, "live_submission_ready": false, "live_submission_blockers": [ "github_write_credentials", "owner_live_execution_approval" ] }, "detector_probe": { "requested": true, "status": "ok", "detected_count": 1, "external_writes_performed": false }, "authority": { "readiness_external_writes_performed": false, "public_feed_probe_read_only": true, "secrets_included": false } } } } } } } }, "/api/cron/algora-bounty-poll": { "get": { "operationId": "cronPollAlgoraBounties", "summary": "Scheduled Algora bounty detector", "description": "Internal Vercel Cron route. Vercel calls this production path with CRON_SECRET in the Authorization header. It dry-runs by default and imports Askuno registry state only when ASKUNO_ALGORA_CRON_IMPORT_ENABLED=true is configured server-side. The durable runtime contract is verified locally with npm run verify:algora-durable-runtime-contract across Supabase schema, migration, cron config, cron auth, default dry-run behavior, production durable-store guards, and the private cron-import flow. It performs no GitHub, Algora claim, payment, banking, or live credit authority writes.", "tags": [ "Bounties" ], "security": [ { "cronSecret": [] } ], "responses": { "200": { "description": "Scheduled poll result.", "content": { "application/json": { "example": { "ok": true, "source": "algora", "mode": "askuno_managed_poll", "dry_run": true, "detected_count": 1, "imported_count": 0, "actor": { "kind": "cron", "source": "cron-secret" }, "external_actions_performed": false } } } } } } }, "/api/bounties/algora/available": { "get": { "operationId": "listAskunoManagedAlgoraBounties", "summary": "List Askuno-registered Algora bounty work", "description": "Returns user-safe Askuno-managed bounty cards from registered bounty state. By default it only returns claimable bounties; pass include_unavailable=true to inspect stale or already-assigned work with a claimability reason. This route gives agents and users the bounty info, bounty-work free cap, start URL, claim URL, completion URL, and payout boundary. It performs no external writes and production requires durable Supabase state.", "tags": [ "Bounties" ], "security": [], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "example": 50 }, { "name": "include_unavailable", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": false } ], "responses": { "200": { "description": "Askuno-managed bounty work available to users.", "content": { "application/json": { "example": { "ok": true, "source": "algora", "mode": "askuno_managed", "count": 1, "available": [ { "bounty_id": "bty_algora_123", "mission_id": "algora-bty_algora_123", "title": "Implement the bounty feature", "target_repo": "example-org/example-repo", "issue_number": 42, "issue_label": "#42", "issue_url": "https://github.com/example-org/example-repo/issues/42", "algora_claim_command_hint": "/claim #42", "amount_usd": 1500, "free_cap": { "credits": 25000, "requestsPerDay": 2500 }, "payout_recipient": { "recipient": "askuno", "receiverRefExposed": false, "external_payment_actions": "blocked_until_owner_approval" }, "claim_url": "/api/bounties/algora/bty_algora_123/claim", "complete_url": "/api/bounties/algora/bty_algora_123/complete", "completion_contract": { "accepted_modes": [ "code_submission", "askuno_owned_existing_pr" ], "preferred_mode": "code_submission", "existing_pr": { "required_fields": [ "pr_url", "solver_github_login" ], "pr_body_should_include": "/claim #42", "ownership_required": "askuno_solver_identity" }, "code_submission": { "required_fields": [ "repo", "head_branch", "commit_message", "solver_github_login" ], "required_one_of": [ [ "patch_text", "private_artifact_url", "code_artifact_ref" ] ], "artifact_inputs": { "private_artifact_url": "Use a private link or branch reference that Askuno reviewers can access without exposing the solution publicly.", "code_artifact_ref": "Use when Askuno/Hermes already has a branch, patch file, or artifact reference.", "patch_text": "Paste a git diff or patch directly; Askuno stores it in the claim for Hermes review and branch preparation." }, "access_notes": "Explain how Askuno reviewers can open the private artifact without public GitHub exposure. Do not paste passwords, API keys, or tokens.", "pr_body_will_include": "/claim #42" }, "external_actions_performed_on_submit": false }, "claimability": { "claimable": true, "reason": null, "active_claims_count": 0 }, "external_actions_performed": false } ] } } } }, "503": { "description": "Production-like runtime is missing durable Askuno bounty state." } } } }, "/api/bounties/algora/register": { "post": { "operationId": "registerAlgoraBounty", "summary": "Register an Algora bounty for Askuno-managed work", "description": "Operator-only private workflow. Registers an Algora bounty inside Askuno so a user can work on it. Registration persists to Supabase when configured, production mutations require durable persistence, and the response prepares Askuno-managed payout metadata without external claim, payment, GitHub, or Algora writes.", "tags": [ "Bounties" ], "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "bounty_id": "bty_algora_123" } } } }, "responses": { "201": { "description": "Bounty registered.", "content": { "application/json": { "example": { "ok": true, "registration": { "bounty_id": "bty_algora_123", "work_mode": "askuno_managed", "payout": { "recipient": "askuno", "external_payment_actions": "blocked_until_owner_approval" } }, "persistence": { "registration": { "persistence": "supabase-postgres" } } } } } } } } }, "/api/bounties/algora/{bounty_id}/mission-packet": { "get": { "operationId": "getAlgoraBountyMissionPacket", "summary": "Get one Askuno-managed Algora bounty packet", "description": "Returns the safe user/agent packet for one registered Askuno-managed Algora bounty: issue details, free cap, claimability, start/claim/status/complete URLs, Askuno payout boundary, and authority flags. It performs no external writes and exposes no credentials or payment receiver references.", "tags": [ "Bounties" ], "security": [], "parameters": [ { "name": "bounty_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "bty_algora_123" } ], "responses": { "200": { "description": "Safe Askuno-managed mission packet for one registered bounty.", "content": { "application/json": { "example": { "ok": true, "schema": "askuno-algora-mission-packet/v0.1", "source": "algora", "mode": "askuno_managed", "bounty": { "bounty_id": "bty_algora_123", "mission_id": "algora-bty_algora_123", "title": "Implement the bounty feature", "target_repo": "example-org/example-repo", "issue_number": 42, "issue_label": "#42", "issue_url": "https://github.com/example-org/example-repo/issues/42", "algora_claim_command_hint": "/claim #42", "mission_packet_url": "/api/bounties/algora/bty_algora_123/mission-packet", "claim_url": "/api/bounties/algora/bty_algora_123/claim", "status_url": "/api/bounties/algora/bty_algora_123/status", "complete_url": "/api/bounties/algora/bty_algora_123/complete" }, "assignment": { "claimability": { "claimable": true, "reason": null }, "exclusive_assignment": true }, "economics": { "user_free_cap": { "credits": 25000, "requestsPerDay": 2500 }, "payout_recipient": { "recipient": "askuno", "receiverRefExposed": false }, "future_user_payout_boundary": "future_internal_banking_or_wise_flow" }, "issue": { "title": "Implement the bounty feature", "target_repo": "example-org/example-repo", "issue_number": 42, "issue_label": "#42", "issue_url": "https://github.com/example-org/example-repo/issues/42", "algora_claim_command_hint": "/claim #42" }, "completion_contract": { "endpoint": "/api/bounties/algora/bty_algora_123/complete", "accepted_modes": [ "code_submission", "askuno_owned_existing_pr" ], "preferred_mode": "code_submission", "existing_pr": { "required_fields": [ "pr_url", "solver_github_login" ], "pr_body_should_include": "/claim #42", "ownership_required": "askuno_solver_identity", "result_status": "paperwork_ready" }, "code_submission": { "required_fields": [ "repo", "head_branch", "commit_message", "solver_github_login" ], "required_one_of": [ [ "patch_text", "private_artifact_url", "code_artifact_ref" ] ], "optional_fields": [ "base_branch", "pull_request_title", "pull_request_body" ], "artifact_inputs": { "private_artifact_url": "Use a private link or branch reference that Askuno reviewers can access without exposing the solution publicly.", "code_artifact_ref": "Use when Askuno/Hermes already has a branch, patch file, or artifact reference.", "patch_text": "Paste a git diff or patch directly; Askuno stores it in the claim for Hermes review and branch preparation." }, "access_notes": "Explain how Askuno reviewers can open the private artifact without public GitHub exposure. Do not paste passwords, API keys, or tokens.", "pr_body_will_include": "/claim #42", "result_status": "code_submission_ready" }, "external_actions_performed_on_submit": false }, "authority": { "mission_packet_external_actions_performed": false, "github_write": false, "algora_write": false, "payment_action": false, "banking_action": false, "credentials_included": false, "receiver_ref_exposed": false } } } } }, "404": { "description": "The bounty has not been registered in Askuno." }, "503": { "description": "Production-like runtime is missing durable Askuno bounty state." } } } }, "/api/bounties/algora/{bounty_id}/claim": { "post": { "operationId": "claimAlgoraBounty", "summary": "Start work on a registered Algora bounty", "description": "Creates a durable Askuno-side user work claim for a previously registered Algora bounty and returns the bounty work free cap. This does not create an Algora claim.", "tags": [ "Bounties" ], "security": [ { "apiToken": [] }, { "bearerApiKey": [] }, { "sessionAuth": [] } ], "parameters": [ { "name": "bounty_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "bty_algora_123" } ], "responses": { "201": { "description": "User bounty work claim started.", "content": { "application/json": { "example": { "ok": true, "claim": { "bounty_id": "bty_algora_123", "status": "user_working", "free_cap": { "credits": 25000, "requestsPerDay": 2500 } }, "persistence": { "claim": { "persistence": "supabase-postgres" } } } } } } } } }, "/api/bounties/algora/{bounty_id}/start": { "post": { "operationId": "startAlgoraBountyWork", "summary": "Issue a bounty-scoped token and reserve the Askuno claim", "description": "Atomically starts user work for a registered, currently claimable Askuno-managed Algora bounty. It issues the bounty-work free cap token and reserves the Askuno-side claim for the token user. The private HTTP verifier proves that token can authenticate /api/chat, debit only the token usage meter, and expose updated balance through /api/api-usage. It performs no GitHub, Algora, payment, banking, or live credit-authority writes.", "tags": [ "Bounties" ], "security": [], "parameters": [ { "name": "bounty_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "bty_algora_123" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contact", "useCase" ], "properties": { "contact": { "type": "string", "description": "Email, Discord, or GitHub handle.", "example": "builder@example.com" }, "useCase": { "type": "string", "example": "Complete this Askuno-managed Algora bounty." } } } } } }, "responses": { "201": { "description": "Bounty token issued and Askuno claim reserved.", "content": { "application/json": { "example": { "ok": true, "trial": { "offer": "Bounty work free cap", "credits": 25000, "bountyWork": true, "bountyEligibility": { "source": "registered_askuno_algora_bounty", "free_cap_requires_registered_claimable_bounty": true } }, "tokenHeader": "x-askuno-api-token", "token": "askuno_sk_...", "claim": { "bounty_id": "bty_algora_123", "status": "user_working", "free_cap": { "credits": 25000, "requestsPerDay": 2500 } }, "start": { "mode": "token_and_claim", "external_actions_performed": false } } } } }, "409": { "description": "The bounty is no longer claimable for the free cap." } } } }, "/api/bounties/algora/{bounty_id}/status": { "get": { "operationId": "getAlgoraBountyClaimStatus", "summary": "Get user-visible Algora bounty work status", "description": "Returns a sanitized status view for a user's Askuno-managed Algora bounty claim, including next action, operator-review stage, code/PR state, live execution receipt state, Askuno payment receipt state, bounty free-cap lifecycle, and the future banking/Wise user-routing boundary. It performs no external writes and never exposes payment receiver references.", "tags": [ "Bounties" ], "security": [ { "apiToken": [] }, { "bearerApiKey": [] }, { "sessionAuth": [] } ], "parameters": [ { "name": "bounty_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "bty_algora_123" }, { "name": "claim_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "algora-claim-abc123" } ], "responses": { "200": { "description": "Current user bounty status.", "content": { "application/json": { "example": { "ok": true, "source": "algora", "mode": "askuno_managed", "claim_status": { "claim_id": "algora-claim-abc123", "bounty_id": "bty_algora_123", "status": "code_submission_ready", "stage": "operator_review", "next_action": "create_hermes_submission_packet", "bounty": { "target_repo": "example-org/example-repo", "issue_number": 42, "issue_label": "#42", "algora_claim_command_hint": "/claim #42" }, "hermes": { "paperwork_ready": true, "submission_packet_ready": false, "live_execution_completed": false }, "payment": { "recipient": "askuno", "status": "not_recorded", "receiverRefExposed": false, "user_routing": "future_internal_banking_or_wise_flow" }, "free_cap_lifecycle": { "schema": "askuno-bounty-free-cap-lifecycle/v0.1", "state": "active_under_review_or_execution", "active": true, "terminal": false, "renewable": false, "token_revocation_performed": false, "live_credit_authority_changed": false } }, "external_actions_performed": false } } } }, "404": { "description": "The user has not claimed this bounty yet." } } } }, "/api/bounties/algora/{bounty_id}/complete": { "post": { "operationId": "completeAlgoraBounty", "summary": "Prepare Hermes paperwork for a completed bounty", "description": "Records private user completion evidence into the Askuno claim and returns the Hermes paperwork packet for GitHub PR and external bounty claim/payment steps. The preferred request provides a code_submission object with patch_text, private_artifact_url, or code_artifact_ref so Askuno can create or submit the managed PR or external bounty claim after review and owner approval. Existing PR URLs are valid only when already Askuno-owned or controlled by an authorized Askuno solver identity. The response includes a redacted submission_dossier with PR ownership, Askuno payout recipient, claim-command check, secret-shaped PR payload scan, and owner review checklist. Live external writes remain owner-gated.", "tags": [ "Bounties" ], "security": [ { "apiToken": [] }, { "bearerApiKey": [] }, { "sessionAuth": [] } ], "parameters": [ { "name": "bounty_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "bty_algora_123" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "pr_url": "https://github.com/example-org/example-repo/pull/77", "solver_github_login": "askuno-bot", "code_submission": { "repo": "example-org/example-repo", "base_branch": "main", "head_branch": "askuno/bty-algora-123", "private_artifact_url": "https://private-review.example.com/share/askuno-bounty-123", "patch_text": "diff --git a/src/example.js b/src/example.js\\n--- a/src/example.js\\n+++ b/src/example.js\\n@@ -1 +1 @@\\n-old\\n+new", "access_notes": "Askuno reviewers can open the private link. No password, API key, or token is included.", "commit_message": "Implement Algora bounty 123" } } } } }, "responses": { "200": { "description": "Hermes paperwork packet prepared.", "content": { "application/json": { "example": { "ok": true, "claim": { "status": "paperwork_ready" }, "hermes_paperwork": { "mode": "askuno_managed", "external_actions": "owner_or_hermes_gated", "submission_dossier": { "schema": "askuno-hermes-submission-dossier/v0.1", "github_pr": { "body_contains_claim_command": true, "body_secret_scan_passed": true, "body_preview_redacted": true }, "payment": { "recipient": "askuno", "receiverRefExposed": false } } }, "persistence": { "claim": { "persistence": "supabase-postgres" } } } } } } } } }, "/api/admin/bounties/algora/paperwork": { "get": { "operationId": "listAlgoraHermesPaperwork", "summary": "List Algora bounty claims ready for Hermes", "description": "Operator-only queue for completed Askuno-managed bounty claims backed by durable Askuno state when Supabase is configured. Returns prepared Hermes paperwork and code-submission refs. It performs no external writes.", "tags": [ "Bounties" ], "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "Ready paperwork list.", "content": { "application/json": { "example": { "ok": true, "count": 1, "ready": [ { "claim_id": "algora-claim-abc", "bounty_id": "bty_algora_123", "status": "code_submission_ready" } ], "externalActionsPerformed": false, "persistence": "supabase-postgres" } } } } } } }, "/api/admin/bounties/algora/hermes-tasks": { "get": { "operationId": "listAlgoraHermesTasks", "summary": "List Hermes next-action tasks for Algora bounty claims", "description": "Operator-only task queue for Hermes. Converts Askuno-managed Algora claim statuses into explicit next-action tasks with endpoint, method, request body, expected next status, owner-approval boundary, readiness booleans, and external-write classification. With include_waiting=true it also surfaces accepted outcomes waiting for Askuno payment receipt recording. Reading the queue performs no external writes and includes no secrets or payment receiver references.", "tags": [ "Bounties" ], "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "example": 50 }, { "name": "include_waiting", "in": "query", "required": false, "schema": { "type": "boolean" }, "example": false } ], "responses": { "200": { "description": "Hermes task queue.", "content": { "application/json": { "example": { "ok": true, "mode": "askuno_managed_hermes_tasks", "count": 1, "tasks": [ { "task_id": "algora-hermes-algora-claim-abc-code_submission_ready", "claim_id": "algora-claim-abc", "bounty_id": "bty_algora_123", "status": "code_submission_ready", "next_action": "create_hermes_submission_packet", "endpoint": "/api/admin/bounties/algora/submission-packet", "method": "POST", "request_body": { "claim_id": "algora-claim-abc" }, "external_writes_required": false, "owner_approval_required": false }, { "task_id": "algora-hermes-algora-claim-def-bounty_outcome_recorded", "claim_id": "algora-claim-def", "bounty_id": "bty_algora_123", "status": "bounty_outcome_recorded", "stage": "payment_reconciliation", "next_action": "wait_for_askuno_payment_receipt_then_record_non_secret_receipt_ref", "endpoint": "/api/admin/bounties/algora/outcome", "method": "POST", "request_body": { "claim_id": "algora-claim-def", "outcome": { "status": "accepted", "payment_status": "received", "receipt_ref": "non_secret_receipt_reference_required" } }, "external_writes_required": false, "owner_approval_required": false } ], "authority": { "queue_read_external_actions_performed": false, "credentials_included": false } } } } } } } }, "/api/admin/bounties/algora/hermes-advance": { "post": { "operationId": "advanceAlgoraHermesWorkflow", "summary": "Advance safe Hermes steps for an Algora claim", "description": "Operator-only safe execution helper. It advances one local Hermes step by default, or advances until the owner gate when `until` is `owner_gate`. It can create the submission packet, dry-run receipt, private execution receipt, and live execution approval packet, then stops before live GitHub or Algora writes. The private branch-prep verifier proves the code-submission side in a temporary local git worktree by applying the synthetic code artifact, committing it on the configured head branch, verifying the head ref exists before PR creation, removing the temporary worktree, and performing no remote push or GitHub write. This endpoint refuses `confirm_live_execution`; live submission remains on `/api/admin/bounties/algora/execute-live`.", "tags": [ "Bounties" ], "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "claim_id": "algora-claim-abc", "until": "owner_gate" } } } }, "responses": { "200": { "description": "Safe Hermes steps advanced.", "content": { "application/json": { "example": { "ok": true, "mode": "askuno_managed_safe_hermes_advance", "advance_mode": "until_owner_gate", "initial_status": "code_submission_ready", "final_status": "live_execution_packet_ready", "advanced_count": 4, "stop_reason": "owner_gate_reached", "steps": [ { "action": "create_hermes_submission_packet", "external_writes_performed": false }, { "action": "execute_hermes_dry_run", "external_writes_performed": false }, { "action": "complete_private_branch_preparation_simulation", "branch_preparation": { "schema": "askuno-github-branch-preparation-private-result/v0.1", "action": "prepare_head_branch_from_code_artifact", "git_push_performed": false }, "external_writes_performed": false }, { "action": "create_live_execution_approval_packet", "external_writes_performed": false } ], "authority": { "external_writes_performed": false, "stopped_before_live_execution": true, "github_write": false, "algora_write": false, "payment_action": false, "banking_action": false, "live_credit_authority_changed": false } } } } } } } }, "/api/admin/bounties/algora/hermes-runtime-tick": { "post": { "operationId": "tickAskunoHermesRuntime", "summary": "Run one Askuno-owned Hermes runtime tick", "description": "Operator-only Askuno Hermes runtime entrypoint. It consumes the Algora Hermes task queue directly, can review completion evidence when the runtime supplies an explicit approve/reject decision, advances safe local Hermes steps, and stops before owner-gated live execution. With include_waiting=true, confirm_payment_received=true, and a non-secret payment_receipt_ref, it can record an observed Askuno payment receipt for a payment_reconciliation waiting task. It refuses live-execution confirmation and performs no GitHub, Algora, payment, banking, Wise, or credit-authority writes.", "tags": [ "Bounties" ], "security": [ { "sessionAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "example": { "tick_mode": "until_owner_gate", "completion_review_decision": "approve", "completion_review": { "reviewer": "askuno-hermes-runtime", "tests_reported": "runtime review passed" }, "include_waiting": false, "confirm_payment_received": false, "payment_receipt_ref": "non_secret_receipt_reference_when_recording_payment" } } } }, "responses": { "200": { "description": "Runtime tick completed or stopped at the next required gate.", "content": { "application/json": { "example": { "ok": true, "schema": "askuno-hermes-runtime-tick/v0.1", "mode": "askuno_owned_hermes_runtime_tick", "runtime_owner": "askuno", "runtime_boundary": "askuno_app_runtime", "target_agent": "askuno-hermes-runtime", "tick_mode": "until_owner_gate", "advanced_count": 5, "stop_reason": "owner_gate_reached", "steps": [ { "action": "review_completion_evidence", "actual_status": "code_submission_ready" }, { "action": "create_hermes_submission_packet", "actual_status": "hermes_submission_ready" }, { "action": "execute_hermes_dry_run", "actual_status": "hermes_dry_run_executed" }, { "action": "complete_private_branch_preparation_simulation", "actual_status": "hermes_private_execution_completed", "branch_preparation": { "schema": "askuno-github-branch-preparation-private-result/v0.1", "action": "prepare_head_branch_from_code_artifact", "git_push_performed": false } }, { "action": "create_live_execution_approval_packet", "actual_status": "live_execution_packet_ready" } ], "final_task": { "next_action": "execute_owner_approved_live_submission", "endpoint": "/api/admin/bounties/algora/execute-live", "owner_approval_required": true, "external_writes_required": true }, "authority": { "external_writes_performed": false, "live_execution_performed": false, "github_write": false, "algora_write": false, "payment_action": false, "banking_action": false, "wise_action": false, "live_credit_authority_changed": false, "credentials_included": false, "receiver_ref_exposed": false, "stopped_before_live_execution": true } } } } } } } }, "/api/admin/bounties/algora/submission-packet": { "post": { "operationId": "createAlgoraHermesSubmissionPacket", "summary": "Create a Hermes submission packet", "description": "Operator-only dry-run handoff packet for Hermes. It stores the handoff on the Askuno claim and packages GitHub PR creation/confirmation, Algora claim preparation, payment-request preparation, and a redacted submission_dossier behind a separate owner approval gate.", "tags": [ "Bounties" ], "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "claim_id": "algora-claim-abc" } } } }, "responses": { "200": { "description": "Submission packet created.", "content": { "application/json": { "example": { "ok": true, "submission_packet": { "schema": "askuno-hermes-submission-packet/v0.1", "mode": "dry_run_ready", "submission_dossier": { "schema": "askuno-hermes-submission-dossier/v0.1", "github_pr": { "body_secret_scan_passed": true } }, "authority": { "requires_owner_approval": true, "external_writes_performed": false } } } } } } } } }, "/api/admin/bounties/algora/execute-dry-run": { "post": { "operationId": "executeAlgoraHermesDryRun", "summary": "Create a Hermes dry-run execution receipt", "description": "Operator-only dry-run endpoint that consumes a stored Hermes submission packet and writes a receipt showing the exact GitHub PR, Algora claim, payment-request actions, and redacted submission dossier Hermes would perform after separate owner approval. It performs no live external writes and includes no secrets.", "tags": [ "Bounties" ], "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "claim_id": "algora-claim-abc" } } } }, "responses": { "200": { "description": "Dry-run execution receipt created.", "content": { "application/json": { "example": { "ok": true, "dry_run_receipt": { "schema": "askuno-hermes-algora-dry-run-execution/v0.1", "mode": "dry_run", "authority": { "requires_owner_approval": true, "external_writes_performed": false, "github_write": false, "algora_write": false, "payment_action": false }, "github_execution_plan": { "action": "create_pull_request", "path": "/repos/example-org/example-repo/pulls" } } } } } } } } }, "/api/admin/bounties/algora/private-execution": { "post": { "operationId": "completeAlgoraHermesPrivateExecution", "summary": "Complete the private Hermes execution simulation", "description": "Operator-only private QA endpoint that consumes a dry-run receipt and persists a private execution receipt showing simulated code submission, Algora claim preparation, and Askuno payment-request preparation. It performs no live GitHub, Algora, payment, banking, or credit writes and is disabled in production-like runtimes.", "tags": [ "Bounties" ], "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "claim_id": "algora-claim-abc" } } } }, "responses": { "200": { "description": "Private execution simulation completed.", "content": { "application/json": { "example": { "ok": true, "private_execution_receipt": { "schema": "askuno-hermes-algora-private-execution/v0.1", "mode": "private_simulation", "authority": { "external_writes_performed": false, "github_write": false, "algora_write": false, "payment_action": false }, "code_submission_result": { "action": "create_pull_request", "status": "prepared_private_simulation" }, "algora_claim_result": { "status": "prepared_private_simulation", "payout_recipient": "askuno" }, "payment_request_result": { "recipient": "askuno", "receiverRefConfigured": true, "receiverRefExposed": false } }, "claim": { "status": "hermes_private_execution_completed" } } } } }, "403": { "description": "Private execution simulation is disabled in production-like runtimes." } } } }, "/api/admin/bounties/algora/go-live-plan": { "get": { "operationId": "getAlgoraGoLivePlan", "summary": "Build the owner-gated Algora go-live plan", "description": "Operator-only no-write readiness packet for moving the Askuno-managed Algora bounty lane from private proof to live execution. It composes runtime readiness, optional claim readiness, required server env names, an owner activation packet for the live PR handoff, a payment reconciliation packet for non-secret Askuno receipt recording, exact owner-gated steps, a full-system gate report, and no-secret/no-write authority flags. The local verifier npm run verify:algora-production-env-contract exercises incomplete and fully configured redacted production-like env fixtures, proves the durable cron/import gate can become ready, confirms live PR submission waits for claim-bound owner approval, and proves a claim-bound production-like dry-run can generate a ready owner activation packet without executing it. It performs no GitHub, Algora, payment, banking, or credit writes.", "tags": [ "Bounties" ], "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "claim_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional Askuno Algora claim id to include in the live execution scope." }, { "name": "check_public_feed", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "When true, performs a read-only public Algora detector probe." } ], "responses": { "200": { "description": "No-write go-live plan.", "content": { "application/json": { "example": { "ok": true, "schema": "askuno-algora-go-live-plan/v0.1", "source": "algora", "mode": "askuno_managed", "purpose": "operator_readiness_packet_before_live_algora_bounty_execution", "readiness_summary": { "production_promotion_ready": false, "live_submission_ready": false, "claim_scope_status": "not_requested", "claim_ready_for_live_execution": false, "ready_for_live_execution": false, "blocker_count": 4 }, "blockers": [ "durable_supabase_service_role", "github_write_credentials", "owner_live_execution_approval", "claim_id_for_live_execution" ], "required_server_env": [ { "name": "ASKUNO_ALGORA_ORGS", "required_for": "bounty_detection", "configured": true, "secret": false, "value_exposed": false }, { "name": "SUPABASE_URL", "required_for": "durable_registry_claims_cron_and_live_execution", "configured": true, "secret": false, "value_exposed": false }, { "name": "SUPABASE_ANON_KEY", "required_for": "durable_registry_claims_cron_and_live_execution", "configured": true, "secret": true, "value_exposed": false }, { "name": "SUPABASE_SERVICE_ROLE_KEY", "required_for": "durable_registry_claims_cron_and_live_execution", "configured": true, "secret": true, "value_exposed": false }, { "name": "ASKUNO_GITHUB_WRITE_TOKEN", "alternate": "GITHUB_TOKEN", "required_for": "owner_approved_live_pr_submission", "configured": false, "secret": true, "value_exposed": false } ], "owner_activation_packet": { "schema": "askuno-algora-owner-activation-packet/v0.1", "mode": "owner_gated_live_pr_submission", "purpose": "execute_one_claim_bound_askuno_managed_algora_pr_submission", "ready_for_owner_execution": false, "claim_id": "{claim_id}", "claim_id_is_placeholder": true, "endpoint": "POST /api/admin/bounties/algora/execute-live", "request_body_template": { "claim_id": "{claim_id}", "confirm_live_execution": true }, "preflight_requirements": [ { "id": "claim_loaded", "satisfied": false, "blockers": [ "registered_claim_id" ] }, { "id": "owner_claim_bound_approval_ready", "satisfied": false, "blockers": [ "owner_live_execution_approval" ] } ], "expected_receipt": { "schema": "askuno-algora-live-execution/v0.1", "required_fields": [ "github_result.pr_url", "github_result.issue_open_checked", "github_result.duplicate_pr_guard_checked", "github_result.pr_body_claim_command_checked" ], "payment_action_must_be_false": true, "live_credit_authority_change_must_be_false": true, "receiver_ref_exposed_must_be_false": true }, "failure_handling": { "retryable_receipt_schema": "askuno-algora-live-execution-failure/v0.1", "retry_task_next_action": "retry_owner_approved_live_submission" }, "authority": { "generated_packet_only": true, "external_writes_performed": false, "secrets_included": false, "receiver_ref_exposed": false } }, "payment_reconciliation_packet": { "schema": "askuno-algora-payment-reconciliation-packet/v0.1", "mode": "record_askuno_bounty_payment_receipt", "purpose": "record_non_secret_askuno_payment_receipt_after_external_maintainer_acceptance", "ready_for_receipt_recording": false, "claim_id": "{claim_id}", "claim_id_is_placeholder": true, "endpoint": "POST /api/admin/bounties/algora/outcome", "request_body_template": { "claim_id": "{claim_id}", "outcome": { "status": "accepted", "payment_status": "received", "receipt_ref": "non_secret_receipt_reference_required" } }, "expected_receipt": { "schema": "askuno-algora-bounty-outcome/v0.1", "askuno_received_payment_must_be_true": true, "receipt_ref_present_must_be_true": true, "receiver_ref_exposed_must_be_false": true, "payment_action_must_be_false": true, "banking_action_must_be_false": true, "live_credit_authority_change_must_be_false": true }, "user_payout_boundary": { "status_after_payment": "pending_future_payout_routing", "next_action": "design_and_approve_internal_banking_or_wise_flow", "payment_action_performed_by_packet": false, "banking_action_performed_by_packet": false, "wise_action_performed_by_packet": false, "live_credit_authority_changed_by_packet": false }, "authority": { "generated_packet_only": true, "internal_state_write_required_when_executed": true, "external_writes_performed": false, "payment_action_performed": false, "banking_action_performed": false, "wise_action_performed": false, "live_credit_authority_changed": false, "secrets_included": false, "credential_values_exposed": false, "receiver_ref_exposed": false } }, "go_live_sequence": [ { "order": 4, "action": "execute_askuno_owned_pr_submission_with_algora_claim_command", "status": "blocked", "endpoint": "POST /api/admin/bounties/algora/execute-live", "external_writes_required": true, "owner_approval_required": true }, { "order": 5, "action": "record_external_maintainer_outcome_and_askuno_payment_receipt", "status": "waiting_for_external_maintainer_and_payment", "endpoint": "POST /api/admin/bounties/algora/outcome", "payment_action_required": false, "owner_approval_required": true } ], "full_system_gate_report": { "schema": "askuno-algora-full-system-gates/v0.1", "achieved": false, "gate_count": 6, "open_gate_ids": [ "production_runtime_deploy", "durable_supabase_and_cron_env", "real_github_pr_submission", "real_algora_maintainer_acceptance_and_payment", "wise_or_internal_user_payout_routing", "live_credit_authority_change" ], "authority": { "generated_report_only": true, "external_writes_performed": false, "secrets_included": false, "receiver_ref_exposed": false } }, "authority": { "generated_plan_only": true, "external_writes_performed": false, "github_write_performed": false, "algora_write_performed": false, "payment_action_performed": false, "banking_action_performed": false, "live_credit_authority_changed": false, "secrets_included": false, "credential_values_exposed": false, "receiver_ref_exposed": false } } } } } } } }, "/api/admin/bounties/algora/live-readiness": { "get": { "operationId": "getAlgoraClaimLiveReadiness", "summary": "Check one Algora claim before live execution", "description": "Operator-only non-mutating preflight for one Askuno-managed Algora claim. It reports lifecycle readiness, server-side gate booleans, exact blocking requirements, next action, and a sanitized live execution packet preview without performing GitHub, Algora, payment, banking, or credit writes.", "tags": [ "Bounties" ], "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "claim_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Askuno Algora claim id to preflight." } ], "responses": { "200": { "description": "Claim live-readiness preflight.", "content": { "application/json": { "example": { "ok": true, "schema": "askuno-algora-claim-live-readiness/v0.1", "claim": { "id": "algora-claim-abc", "bounty_id": "bty_algora_123", "status": "live_execution_packet_ready" }, "ready_for_live_execution": false, "can_execute_live": false, "readiness": { "ownerApprovalFlagPresent": false, "ownerApprovalClaimBound": false, "ownerApprovedClaimMatches": false, "approvedClaimIdExposed": false }, "blocking_requirements": [ "github_write_credentials", "askuno_algora_solver_login", "durable_supabase_service_role", "owner_live_execution_approval" ], "next_action": "resolve_live_execution_blockers", "live_execution_packet_preview": { "schema": "askuno-algora-live-execution-approval-packet/v0.1", "required_pr_body_contains": "/claim #42", "receiverRefExposed": false }, "authority": { "readiness_external_writes_performed": false, "credentials_included": false, "github_write": false, "algora_write": false, "payment_action": false, "banking_action": false, "live_credit_authority_change": false } } } } } } } }, "/api/admin/bounties/algora/live-execution-packet": { "post": { "operationId": "createAlgoraLiveExecutionPacket", "summary": "Create the owner-gated live execution approval packet", "description": "Operator-only endpoint that packages the exact GitHub, Algora, and Askuno payment actions Hermes would need for live execution. Askuno-managed mode defaults to Algora's GitHub PR body /claim command workflow, with the solver identity coming from server-side Askuno configuration. The response includes an execution_contract naming the target repo, issue, required claim command, PR action, preflight checks, no-payment authority flags, a redacted submission_dossier, and a github_submission_contract for the issue-open check, duplicate PR guard, head-branch ref check, PR create path/body keys, and branch-preparation boundary. Live execution does not create branches or push commits; the prepared head branch must already contain the code artifact before owner-approved PR submission. It reports server-side readiness booleans and required env names without exposing credential values. It performs no live writes and does not authorize execution by itself.", "tags": [ "Bounties" ], "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "claim_id": "algora-claim-abc" } } } }, "responses": { "200": { "description": "Live execution approval packet created.", "content": { "application/json": { "example": { "ok": true, "live_execution_packet": { "schema": "askuno-algora-live-execution-approval-packet/v0.1", "ready_for_live_execution": false, "blocking_requirements": [ "github_write_credentials", "askuno_algora_solver_login", "durable_supabase_service_role", "owner_live_execution_approval" ], "authority": { "requires_owner_approval": true, "live_execution_authorized": false, "external_writes_performed": false, "credentials_included": false }, "planned_actions": { "github": { "action": "create_pull_request", "required_pr_body_contains": "/claim #42" }, "algora_claim": { "action": "submit_algora_claim_via_github_pr_body", "algora_api_write_required": false, "solver_identity_source": "ASKUNO_ALGORA_SOLVER_LOGIN" } }, "execution_contract": { "schema": "askuno-algora-live-execution-contract/v0.1", "target_repo": "example-org/example-repo", "issue_number": 42, "claim_command": "/claim #42", "github_action": "create_pull_request", "pr_body_must_include": "/claim #42", "preflight_checks": { "issue_open_check_required": true, "duplicate_pr_guard_required": true, "head_branch_ref_required": true, "claim_bound_owner_approval_required": true }, "github_submission_contract": { "schema": "askuno-github-live-submission-contract/v0.1", "action": "create_pull_request", "preflight_requests": { "issue_open": { "method": "GET", "path": "/repos/example-org/example-repo/issues/42", "required": true }, "duplicate_pr_guard": { "method": "GET", "path": "/repos/example-org/example-repo/pulls?state=open&head=example-org:askuno/bounty-42&base=main", "required": true }, "head_branch_ref": { "method": "GET", "path": "/repos/example-org/example-repo/git/ref/heads/askuno/bounty-42", "required": true } }, "live_write_request": { "method": "POST", "path": "/repos/example-org/example-repo/pulls", "body_keys": [ "title", "head", "base", "body", "maintainer_can_modify" ], "body_must_include_claim_command": true }, "branch_preparation": { "schema": "askuno-github-branch-preparation-contract/v0.1", "action": "prepare_head_branch_from_code_artifact", "requirement": "head_branch_must_already_contain_code_artifact_before_execute_live", "target_repo": "example-org/example-repo", "base_branch": "main", "head_branch": "askuno/bounty-42", "code_artifact_ref": "askuno://claims/algora-claim-abc/code-artifact", "commit_message": "Implement Algora bounty 42", "required_before_execute_live": true, "required_before_pr_create": true, "execution_mode": "hermes_worktree_or_owner_approved_git_write", "command_templates": [ "git fetch origin {base_branch}", "git checkout -B {head_branch} origin/{base_branch}", "apply code artifact from {code_artifact_ref}", "git add -A", "git commit -m {commit_message}", "git push origin {head_branch}" ], "verification": { "head_branch_ref_path": "/repos/example-org/example-repo/git/ref/heads/askuno/bounty-42", "pr_create_waits_for_head_ref": true, "code_artifact_review_required": true }, "askuno_live_execution_creates_branch": false, "askuno_live_execution_pushes_commits": false, "authority": { "generated_contract_only": true, "external_writes_performed": false, "github_write_performed": false, "git_push_performed": false, "credentials_included": false, "secrets_included": false } } }, "authority": { "external_writes_performed": false, "payment_action_performed": false, "banking_action_performed": false, "credentials_included": false } }, "required_env": { "github": [ "ASKUNO_GITHUB_WRITE_TOKEN", "GITHUB_TOKEN" ], "askuno_solver": [ "ASKUNO_ALGORA_SOLVER_LOGIN" ], "algora": [], "payment_receiver": [ "ASKUNO_ALGORA_PAYMENT_RECEIVER_REF" ], "persistence": [ "SUPABASE_URL", "SUPABASE_ANON_KEY", "SUPABASE_SERVICE_ROLE_KEY" ], "owner_approval": [ "ASKUNO_ALGORA_LIVE_EXECUTION_APPROVED", "ASKUNO_ALGORA_LIVE_EXECUTION_APPROVED_CLAIM_ID" ] } }, "claim": { "status": "live_execution_packet_ready" } } } } } } } }, "/api/admin/bounties/algora/execute-live": { "post": { "operationId": "executeAlgoraLive", "summary": "Execute an owner-approved Algora bounty submission", "description": "Operator-only endpoint that executes the live GitHub PR submission after the stored live execution packet recomputes as ready and the request explicitly confirms execution. In default Askuno-managed mode, this confirms the target GitHub issue is still open, checks for an existing open PR on the same head/base before creating a new PR, confirms the prepared head branch exists when creation is needed, records the prepared head-ref SHA in the live receipt, creates or confirms the GitHub PR with the Algora /claim command in the PR body, and defers payment until maintainer acceptance. It requires server-side credentials and never returns credential values.", "tags": [ "Bounties" ], "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "claim_id": "algora-claim-abc", "confirm_live_execution": true } } } }, "responses": { "200": { "description": "Live execution completed.", "content": { "application/json": { "example": { "ok": true, "live_execution_receipt": { "schema": "askuno-algora-live-execution/v0.1", "claim_submission_mode": "github_pr_claim_command", "github_result": { "action": "create_pull_request", "status": "created", "issue_open_checked": true, "pr_body_claim_command_checked": true, "duplicate_pr_guard_checked": true, "head_branch_ref_checked": true, "head_branch_ref": "refs/heads/askuno/bounty-42", "head_branch_sha": "0123456789abcdef0123456789abcdef01234567", "pr_url": "https://github.com/example-org/example-repo/pull/88" }, "algora_claim_result": { "action": "submit_algora_claim_via_github_pr_body", "status": "submitted_by_pr_body" }, "authority": { "github_write": true, "algora_write": false, "payment_action": false, "banking_action": false, "credentials_included": false } }, "claim": { "status": "live_execution_completed" } } } } }, "400": { "description": "Missing claim_id or confirm_live_execution." }, "403": { "description": "Live execution packet is not authorized or missing required server-side env." } } } }, "/api/admin/bounties/algora/outcome": { "post": { "operationId": "recordAlgoraBountyOutcome", "summary": "Record Algora bounty outcome and Askuno payment receipt state", "description": "Operator-only endpoint that records an externally observed maintainer/payment outcome for an Askuno-managed Algora bounty claim. It can mark Askuno payment as received when live execution has completed, a server-side receiver reference is configured, and a non-secret receipt_ref is provided. Local private verifiers can opt into explicit private outcome simulation. Accepted paid outcomes also record a non-payment user payout intent for future internal banking or Wise routing. This endpoint does not call Algora, GitHub, payment, banking, Wise, or credit systems.", "tags": [ "Bounties" ], "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "claim_id": "algora-claim-abc", "outcome": { "status": "accepted", "payment_status": "received", "amount_usd": 1500, "external_claim_id": "algora-claim-123", "receipt_ref": "non_secret_receipt_reference" } } } } }, "responses": { "200": { "description": "Outcome recorded.", "content": { "application/json": { "example": { "ok": true, "outcome_receipt": { "schema": "askuno-algora-bounty-outcome/v0.1", "outcome": { "status": "accepted", "maintainer_accepted": true, "live_execution_completed_before_outcome": true, "private_outcome_simulation": false }, "payment": { "recipient": "askuno", "status": "received", "askuno_received_payment": true, "receiverRefConfigured": true, "receiverRefExposed": false, "receipt_ref_required_for_received_status": true, "receipt_ref_present": true, "received_status_requires_live_execution_or_private_simulation": true, "external_payment_actions_performed_by_askuno": false }, "user_payout_intent": { "schema": "askuno-algora-user-payout-intent/v0.1", "status": "pending_future_payout_routing", "payout_due": true, "payout_amount_finalized": false, "next_action": "design_and_approve_internal_banking_or_wise_flow", "authority": { "payment_action_performed": false, "banking_action_performed": false, "wise_action_performed": false, "live_credit_authority_change": false } }, "authority": { "external_writes_performed": false, "payment_action": false, "banking_action": false } }, "claim": { "status": "bounty_payment_received" } } } } } } } }, "/api/agent-skill": { "get": { "operationId": "getAgentSkill", "summary": "Get the Askuno agent credit skill", "description": "Returns agent-readable instructions for connecting an agent or CLI to Askuno, checking API usage, budgeting credits per task, browsing bounty candidates, starting registered Askuno-managed bounty work, and keeping API tokens out of prompts and logs.", "tags": [ "Agent Skill" ], "security": [], "responses": { "200": { "description": "Agent skill returned.", "content": { "application/json": { "example": { "ok": true, "schema": "askuno-agent-skill/v0.1", "name": "askuno-api-credit-skill", "endpoints": { "startTrial": "POST https://askuno.app/api/trials/start", "chat": "POST https://askuno.app/api/chat", "usage": "GET https://askuno.app/api/api-usage", "bountyCandidates": "GET https://askuno.app/api/bounties/candidates", "legacyMissions": "GET https://askuno.app/api/missions", "algoraBounties": "GET https://askuno.app/api/bounties/algora", "algoraAvailableBounties": "GET https://askuno.app/api/bounties/algora/available" }, "creditModel": { "freeTrialUsd": 10, "earnPath": "Use covered credits for registered bounty work; external payouts depend on third-party acceptance and payment." } } } } } } } }, "/api/mailing-list/subscribe": { "post": { "operationId": "subscribeMailingList", "summary": "Join Askuno updates", "description": "Subscribes an email to Askuno product, mission, and agent/CLI update emails. The public response returns only an email preview.", "tags": [ "Updates" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "builder@example.com" }, "interest": { "type": "string", "example": "agent CLI and mission updates" }, "source": { "type": "string", "example": "homepage-updates" } } } } } }, "responses": { "201": { "description": "Subscription accepted.", "content": { "application/json": { "example": { "ok": true, "status": "subscribed", "emailPreview": "bu***@example.com" } } } }, "400": { "description": "Invalid email.", "content": { "application/json": { "example": { "ok": false, "error": "invalid_email" } } } } } } }, "/api/trials/start": { "post": { "operationId": "startAccountlessTrial", "summary": "Start an accountless trial", "description": "Issues a limited API token with $10 free credit after a tiny intake. No account, password, or payment is required. The contact value is hashed for analytics; the raw contact is not stored in the activity payload. Algora bounty-work free caps require a registered, currently claimable bounty id; the preferred user path is POST /api/bounties/algora/{bounty_id}/start so the token and Askuno claim reservation happen together. The token can then call /api/chat and inspect remaining usage through /api/api-usage.", "tags": [ "Trial" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contact", "useCase" ], "properties": { "contact": { "type": "string", "description": "Email, Discord, or GitHub handle.", "example": "agent@example.com" }, "useCase": { "type": "string", "description": "What the human or agent will use Askuno for.", "example": "Test Askuno from Discord before account creation." }, "expectedVolume": { "type": "string", "example": "100 calls/day" }, "apiType": { "type": "string", "example": "chat" } } } } } }, "responses": { "201": { "description": "Trial token issued.", "content": { "application/json": { "example": { "ok": true, "trial": { "offer": "$10 free API credit", "credits": 10000, "usdValue": 10, "noAccountRequired": true, "noMoneyRequired": true }, "tokenHeader": "x-askuno-api-token", "token": "askuno_sk_...", "conversion": { "nextUrl": "/missions.html", "claimWorkspaceUrl": "/signin.html" } } } } }, "400": { "description": "Missing intake field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "contact_required" } } } } } } }, "/api/credits/signup-grant": { "post": { "operationId": "signupGrant", "summary": "Claim new-user signup grant", "description": "Issues a one-time credit grant for new users. Idempotent — calling it twice for the same user returns the existing grant. Requires an active session.", "tags": [ "Credits" ], "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "Grant issued or already exists.", "content": { "application/json": { "example": { "ok": true, "credits": 500, "alreadyGranted": false } } } }, "401": { "description": "Not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "auth_required" } } } } } } }, "/api/api-usage": { "get": { "operationId": "getApiUsage", "summary": "Check API token usage", "description": "Returns request and credit usage for an accountless trial token or authenticated user's API tokens.", "tags": [ "Trial" ], "security": [ { "apiToken": [] }, { "sessionAuth": [] } ], "responses": { "200": { "description": "Usage meter.", "content": { "application/json": { "example": { "ok": true, "authentication": "api-token", "apiToken": { "remaining": { "requests": 999, "credits": 9999 }, "limits": { "dailyCreditLimit": 10000, "requestsPerDay": 1000 } } } } } } } } }, "/api/me": { "get": { "operationId": "getMe", "summary": "Current user profile", "description": "Returns the authenticated user's credit balance, API keys, recent debit history, and claimed missions. Supports both session JWT and bearer API key authentication.", "tags": [ "Account" ], "security": [ { "bearerApiKey": [] }, { "sessionAuth": [] } ], "responses": { "200": { "description": "User profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" }, "example": { "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "balance": 480, "keys": [ { "id": "k1b2c3d4-e5f6-7890-abcd-ef1234567890", "last4": "ab3f", "name": "prod-server", "created_at": "2026-05-01T09:00:00Z", "revoked_at": null, "last_used_at": "2026-05-10T14:23:00Z" } ], "recent_debits": [ { "credits": 1, "source": "chat_call", "created_at": "2026-05-10T14:23:00Z" } ], "claimed_missions": [] } } } }, "401": { "description": "Not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "auth_required" } } } } } } }, "/api/keys/issue": { "post": { "operationId": "issueApiKey", "summary": "Issue a new API key", "description": "Creates and returns a new API key (`ak_…`). The full key is returned **only once** — store it securely. Subsequent calls return a new key each time.", "tags": [ "Keys" ], "security": [ { "sessionAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Optional human label for this key.", "example": "prod-server" } } } } } }, "responses": { "200": { "description": "Key issued. Copy it now — it will not be shown again.", "content": { "application/json": { "example": { "ok": true, "key": "ak_01hwz3r9k8fxbvcnmqsd7jtpe6ab3f", "id": "k1b2c3d4-e5f6-7890-abcd-ef1234567890", "last4": "ab3f" } } } }, "401": { "description": "Not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "auth_required" } } } } } } }, "/api/keys/list": { "get": { "operationId": "listApiKeys", "summary": "List API keys", "description": "Returns all API keys for the authenticated user. Full key values are never returned — only the last 4 characters and metadata.", "tags": [ "Keys" ], "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "Key list.", "content": { "application/json": { "example": { "keys": [ { "id": "k1b2c3d4-e5f6-7890-abcd-ef1234567890", "last4": "ab3f", "name": "prod-server", "created_at": "2026-05-01T09:00:00Z", "revoked_at": null, "last_used_at": "2026-05-10T14:23:00Z" } ] } } } }, "401": { "description": "Not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/keys/revoke": { "post": { "operationId": "revokeApiKey", "summary": "Revoke an API key", "description": "Permanently revokes an API key by ID. Revoked keys are rejected immediately on next use.", "tags": [ "Keys" ], "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "keyId" ], "properties": { "keyId": { "type": "string", "format": "uuid", "example": "k1b2c3d4-e5f6-7890-abcd-ef1234567890" } } } } } }, "responses": { "200": { "description": "Key revoked.", "content": { "application/json": { "example": { "ok": true, "revoked": true } } } }, "401": { "description": "Not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Key not found.", "content": { "application/json": { "example": { "error": "key_not_found" } } } } } } }, "/api/chat": { "post": { "operationId": "chat", "summary": "Send a chat message", "description": "Sends a message to the configured OpenAI-compatible LLM gateway and returns the assistant's reply. Deducts credits from the caller's balance or accountless trial token allowance. Supports session JWT, bearer API key, and x-askuno-api-token authentication.", "tags": [ "Chat" ], "security": [ { "apiToken": [] }, { "bearerApiKey": [] }, { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRequest" }, "example": { "message": "Explain zero-knowledge proofs in two paragraphs.", "modelId": "qwen3:8b" } } } }, "responses": { "200": { "description": "Assistant reply. `weave_call_proof` is present only when call-proof signing is configured and attached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatResponse" } } } }, "401": { "description": "Not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "auth_required" } } } }, "402": { "description": "Insufficient credits.", "content": { "application/json": { "example": { "error": "insufficient_credits", "requiredCredits": 4, "creditsBefore": 0 } } } }, "500": { "description": "LLM gateway error.", "content": { "application/json": { "example": { "error": "llm_error", "message": "Gateway unavailable." } } } } } } }, "/api/missions/{mission_id}/claim": { "post": { "operationId": "claimMission", "summary": "Claim a mission", "description": "Marks a mission as claimed by the authenticated user. A user may only claim each mission once. Returns the claim record.", "tags": [ "Missions" ], "security": [ { "bearerApiKey": [] }, { "sessionAuth": [] } ], "parameters": [ { "name": "mission_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "legacy-review-001" } ], "responses": { "200": { "description": "Mission claimed.", "content": { "application/json": { "example": { "ok": true, "claim": { "mission_id": "legacy-review-001", "status": "claimed", "claimed_at": "2026-05-11T10:00:00Z", "credit_reward": 500 } } } } }, "401": { "description": "Not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Already claimed.", "content": { "application/json": { "example": { "error": "already_claimed" } } } } } } }, "/api/credits/grant": { "post": { "operationId": "grantCredits", "summary": "Server-to-server credit grant (HMAC)", "description": "Issues a credit grant from an authorized Askuno server runtime to a specific user. This endpoint is server-to-server only — never call it from browser code. Authentication requires two headers sent together: `x-weave-timestamp` (Unix seconds as a string) and `x-weave-signature` (hex HMAC-SHA256). The signed string is `\"${timestamp}.${rawBody}\"` (Stripe-style). The shared secret is configured via the `WEAVE_RUNTIME_GRANT_HMAC_KEY` environment variable. Requests with a timestamp older than 300 seconds are rejected. Idempotency is enforced server-side by a Postgres unique constraint on `(source, mission_id)` — duplicate POSTs return the original grant.", "tags": [ "Credits" ], "security": [ { "weaveSignature": [], "weaveTimestamp": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditGrant" }, "example": { "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "credits": 500, "source": "bounty", "mission_id": "bounty-001" } } } }, "responses": { "200": { "description": "Grant recorded.", "content": { "application/json": { "example": { "ok": true, "grantId": "grant_01hwz3r9k8fxbvcnmqsd7jtpe6", "credits": 500 } } } }, "401": { "description": "HMAC signature missing or invalid.", "content": { "application/json": { "example": { "error": "hmac_invalid" } } } } } } }, "/api/call-proof/public-key": { "get": { "operationId": "getCallProofPublicKey", "summary": "Get call-proof public key", "description": "Returns the Ed25519 public key used to sign Askuno call proofs. Use this to verify a non-null `weave_call_proof` value from chat responses.", "tags": [ "Call Proof" ], "security": [], "responses": { "200": { "description": "Public key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallProofPublicKey" }, "example": { "scheme": "weave-call-proof/v1", "algorithm": "Ed25519", "public_key": "MCowBQYDK2VwAyEA...", "header_name": "X-Weave-Call-Proof", "canonical_format": "weave-call-proof|v1|||||", "timestamp_window_seconds": 300 } } } } } } }, "/api/call-proof/verify": { "post": { "operationId": "verifyCallProof", "summary": "Verify a call proof", "description": "Verifies the Ed25519 signature in a call proof against the server's public key. Useful when you want server-side attestation rather than implementing Ed25519 verification yourself.", "tags": [ "Call Proof" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "proof" ], "properties": { "proof": { "type": "string", "description": "X-Weave-Call-Proof header value from a chat response.", "example": "v1.42.1747000000.ab12cd34ef56ab78.qwen3:8b.deadbeefabc123.MEUCIQDabc123" }, "body": { "type": "string", "description": "Optional original canonical request body for body-hash verification." } } } } } }, "responses": { "200": { "description": "Verification result.", "content": { "application/json": { "example": { "valid": true, "decoded": { "version": "v1", "seq": 42, "timestamp": 1747000000, "userHash": "ab12cd34ef56ab78", "model": "qwen3:8b", "bodyHash": "deadbeefabc123" } } } } }, "400": { "description": "Invalid proof format.", "content": { "application/json": { "example": { "valid": false, "reason": "missing_proof" } } } } } } } } }