Skip to content
Skip documentation navigation
Reference

Outcomes API

Prepare a task, authorize a maximum price, and read the result receipt.

5 min read Ormas documentation

Deliveries are checked against the client’s agreed tests. Verification is currently operated by Ormas.

Control-plane URL#

text
https://api.ormas.ai

Use the Ormas MCP client to prepare coding tasks and send them to Outcomes providers. Follow the first-task guide for installation and repository setup.

Authentication#

Use the Ormas key created under Keys (wire format tb_live_…) to authenticate the client. Store it at the hidden ormas login prompt, then check it with ormas doctor. Outcomes customers do not need model-provider keys or a local execution runner. Keep credentials out of task text, command arguments and chat.

Client workflow#

The supported v1 workflow is:

  1. Prepare the task with ormas_prepare_task: the change, frozen independent acceptance check, exact editable and immutable paths, pushed base commit, local verify_cwd, and catalog-backed execution_environment. Preparation confirms the intended base failure in isolation. It is provider-free and submits no job. Every failing acceptance case must fail at a plain assert (an AssertionError). An exception (for example KeyError), an import error, or extra output mixed into the test result is refused before any paid work, with $0 charged: it did not fail at an assertion. Keep warnings and prints out of the result. The check must also fail on the unfixed base. If it already passes, the job ends as no-delivery at $0. Offered task sizes are small, medium and large; large runs as a single attempt against the attempt authorization you set. See the preparation fields and catalog.
  2. Inspect the returned inner packet and choose the maximum price you authorize.
  3. Enqueue with ormas_outcomes_job(action="enqueue", ...), passing that exact inner object as the top-level work_packet argument and your chosen ceiling as payload.reserve_usd. Qualified miners offer a firm price, or an estimate with a hard limit. Your ceiling at submission is a maximum, never the price. An offer within your ceiling is accepted automatically by default; for public repositories, set award_policy to manual at enqueue to choose the offer yourself. A ceiling does not guarantee a provider match. If every miner slot is busy, the job waits as queued instead of being refused. Each client can have up to 5 jobs in flight (queued and running). An unclaimed job ends after 60 minutes as no-delivery with $0 charged. You may set queue_wait_s (1–3600 seconds) in the enqueue payload for a shorter wait, never longer. While waiting, status shows queued and queue_expires_at. Funds for queued jobs are held against your balance and any daily cap at submission.
  4. Save the job ID and poll its status through acceptance and settlement. A job whose miner never delivers settles as no-delivery at $0 on that ordinary status read. status=done can coexist with settlement=pending_acceptance. The acceptance summary reports the frozen required count, decisions and deadline; worker completion alone is not accepted delivery.
  5. Inspect the actual receipt and result reference. Review the diff and rerun the verifier before deciding whether to merge or deploy.

For public bounded tasks, payload.award_policy selects lowest_expected_charge, lowest_expected_total_cost (default), or manual. Compare offers in the portal or use ormas_outcomes_job actions accept_offer, decide_now and update_award_policy while the window is open and no award is committed. See Choose your offer for window timing and exact call shapes. Private Standard repositories currently use a direct claim without a competitive offer book; enqueue rejects award_policy with award_policy_requires_public_bounded_packet. Missing offer-book data can also occur on older jobs, so read any recorded accepted terms rather than infer the claim path.

The wire names /api/runner/v1 and ormas-runner-v1 are internal identifiers and unchanged until the provider-identity release; they do not describe your role.

Data boundary#

Ormas receives task and control metadata, including your task text, acceptance criteria, repository reference, base commit, verification command, file allowlists and authorized ceiling. Keep secrets, environment dumps and raw private logs out of those fields.

Ormas admits public and private GitHub repositories with explicit third-party execution consent. For public repositories, providers and operator-run checkers read anonymously, and Ormas publishes the bounded result artifact to its agreed branch with a short-lived Ormas SN76 GitHub app token for that one repository, or with a saved encrypted GitHub token; neither credential is given to miners or checkers. Private repositories connect through the Ormas SN76 GitHub App in Setup at the Standard service level (repository_access: {"visibility": "private", "sharing": "shared-code-v1"}): the assigned provider, the checker and their AI services can read the code. The result artifact passes through Ormas. This tier makes no zero-data-retention or confidential-computing promise; see Where your code goes and the access instructions.

Billing contract#

Pass → branch + receipt. You are charged the firm price, or the miner’s settled price — never above its limit. Fail → you pay nothing. An estimate is not a settled charge; read the receipt for the result and actual billed amount. Credit-purchase fees are shown separately in Billing.

Offer and receipt fields#

Job status includes offer, or null for legacy jobs without an offer kind. The object contains kind (firm or limit), price_usd, estimate_usd, limit_usd, settled_usd and charged_usd. Firm offers use price_usd; limit offers use estimate_usd and limit_usd. charged_usd is the receipt’s actual customer-billed amount and may be zero. Missing amounts remain unknown, not zero. Settlement and customer billing are separate: never treat an estimate, limit or settlement as proof of a charge.

Limit receipts also record offer_kind, estimate_usd, limit_usd and settled_usd. The console shows Price for firm offers and Estimate · Limit · Charged for limit offers.

Offer kind (firm or limit), service level (Standard or Protected), and GitHub repository visibility (public or private) are separate concepts. Standard is live; the next Protected client offering is still in testing. See Standard and Protected.

Idempotency and safety#

Preserve the original project, packet, submission identity and returned job ID. Recover existing jobs through project reads and job status after a restart or ambiguous network response. Do not create a new task merely to poll an existing one. You do not need to call reconcile after a restart. Reconcile still exists and is safe. Resubmitting after a no-delivery receipt is safe.

Internal verification, key-resolution, and settlement routes are service-to-service interfaces and are not customer APIs.