Skip to main content
Docs

Search documentation

0 articles

    Contents

    Loop run identity reference

    Retain the identity of an invocation before submitting hosted work. These fields let you distinguish an uncertain response from an absent run without resubmitting with a new identity.

    Hosted invocation fields​

    FieldShape and purpose
    Loop IDReturned lowercase UUID of the account-owned loop
    VersionExactly 64 lowercase hexadecimal characters identifying the reviewed immutable package
    InputsJSON object defined by that artifact, not a universal task schema
    Idempotency-Key16–128 letters, digits, underscores or hyphens; retain it for the original invocation
    confirmedVersionRequired string equal to the version in the invocation path
    allowCloudProcessingRequired boolean true for that invocation
    Run IDReturned UUID identifying the accepted execution

    Invocation uses POST /hvy/v1/loops/{loopId}/versions/{version}/invoke. Send only confirmedVersion, allowCloudProcessing and inputs in an application/json body, at most 16,384 UTF-8 bytes. Account ownership comes from the signed-in session, not a body account ID. Browser writes require the permitted same origin.

    Reads and states​

    The route list below separates catalogue review, artifact inspection, invocation lookup and detail read. Invocation lookup returns identity and status; follow its returned ID with the detail read to inspect output.

    HTTP 202 means acceptance. Hosted states are queued, running, completed, failed, uncertain and expired. For completed, check the artifact-specific output before relying on it. uncertain is unresolved outcome, not proof of no execution. A local read timeout does not change the recorded run state.

    Inputs and output have a 24-hour retention deadline from enqueue. A run can retain its recorded status while output becomes null. Null output does not prove the run never executed.

    Use explicit invocation and same-run readback for the action paths. Never include cookies or credentials in the recovery worksheet.

    Responses and refusal codes​

    A successful invocation returns HTTP 202 with ok:true and run:{id,status}. A detail read returns HTTP 200 with ok:true and run:{id,loopId,version,status,createdAt,output}. The output schema belongs to the reviewed artifact; invocation inputs are not included in the detail read.

    ResponseNarrow recovery
    401 authentication_requiredSign in through the owning application, then repeat the read with the same account
    403 application_forbidden or origin_forbiddenUse the intended application's signed-in origin; do not copy credentials or forge the origin
    402 subscription_requiredCheck run capability, subscription and frozen-account state; do not bypass access checks
    400 explicit_version_consent_requiredMatch the confirmed version to the path and confirm processing only after review
    400 inputs_required, invalid_request or idempotency_key_requiredCorrect the documented input shape or key while preserving the original invocation record
    409 idempotency_conflictThe retained key already belongs to a different input hash covering the loop ID, version and inputs. Inspect the original invocation and look up that same key; do not evade the conflict with a new key
    409 version_unavailable_or_idempotency_conflictThe version is unavailable or unapproved. Read the catalogue and look up the original key; preserve the original invocation record rather than changing keys
    404 run_not_foundConfirm the original account and returned UUID or invocation key
    503 loop_service_unavailablePreserve identity and inspect acceptance after recovery; a failed response does not prove nothing was queued

    A request body over the 16,384-byte limit is refused with 413 request_too_large; non-JSON media types receive 415 unsupported_media_type. Resolve these preparation errors before deliberately invoking. Do not send unrecognized body fields or a caller-selected account identity.

    Hosted loop read routes​

    These method/path descriptions use returned identities on the signed-in origin. They are not copy-paste shell commands and start no work.

    GET /hvy/v1/loops
    GET /hvy/v1/loops/{loopId}/versions/{version}/artifact
    GET /hvy/v1/loops/invocations/{idempotencyKey}
    GET /hvy/v1/loops/runs/{runId}

    MDN: HTTP 202 Accepted explains why request acceptance is not completion. Use the owning Loop run record to establish the actual execution state.