Discover catalogs
GET /v1/catalog returns 200, {connections,harnesses,harness_templates,harness_protocols}, with no pagination. Connections contains adapter kind/provider/capabilities and optional setup_url/evidence. Harnesses contains tenant-visible executable definitions; harness_templates is a separate template collection, not a promise that every image is registered or available. Harness_protocols describes adapter protocol contracts.
Register an OCI Harness
POST /v1/harnesses accepts a strict object:
Accepted references use Docker Hub or GHCR repository syntax, not arbitrary URLs.
python:3.12 expands to Docker Hub’s library/python; org/image:tag defaults to Docker Hub; explicit docker.io/... and ghcr.io/... are supported. An omitted tag/digest selects latest. A digest selector must be @sha256: followed by 64 lowercase hexadecimal characters. HTTP(S) schemes, custom registry hosts and host ports are rejected. Prefer an immutable digest for a repeatable registration; a syntactically valid reference still needs a real image implementing the selected Harness protocol.
For private registry authentication, the managed Secret value must be strict JSON {username,password} with nonempty strings. Do not put registry secrets into image URLs or request logs. The resolver checks the supported image/platform contract; current registrations pin linux/amd64. See OCI integration for runnable image requirements.
Save your actual image definition as harness-image.json:
400 harness_entrypoint_missing.
The immutable key is tenant/id/version. Re-registering an identical resolved definition returns it; different content at the same key yields 409 harness_version_conflict. Image tags can move between requests, so preserve the returned digest and use an immutable image reference. OCI and source packages share this version namespace. No public update/delete route is defined here.
Register a source package
POST /v1/harness-packages accepts a strict object:
Paths are at most 240 characters, begin with an alphanumeric/underscore/hyphen and use alphanumeric, underscore, dot, slash or hyphen characters. Empty/
./.. segments, duplicate paths and file/directory collisions are rejected. Content is text, not Base64, ≤262,144 JavaScript string code units per file; total UTF-8 content is at most 512 KiB. This endpoint is not a general dependency installer.
Prepare harness-package.json following the source-package guide, including actual executable protocol implementation:
409 harness_version_conflict.
Registration stores inert data in the control plane. During execution, files are installed and byte-checked in the Sandbox, the interpreter must exist, and the program must implement the declared protocol. Source acceptance alone does not establish tool support, continuation, correctness or isolation beyond the documented Sandbox boundary.
Malformed strict inputs return 400 invalid_request; image-specific registry/manifest failures use resolver errors. Private registry lookup may return secret_not_found (404), secret_disabled (409), secret_store_unavailable (503) or image_registry_credential_invalid (400). A lost registration response should be reconciled against catalog identity/digest rather than changing version to bypass a conflict.
Registration failures
Both registration operations use the common error envelope. The following named failures supplement strict input validation; a transport or unclassified server failure can still use the general error contract.
Private registry Secret failures are listed above. Source-package path, entrypoint, file count, encoding-size and strict-schema violations return
400 invalid_request; a successful package registration does not run the interpreter or validate behavior. Registry reads may retry bounded read failures internally; this does not authorize retrying image publication, cloud allocation or external Tool writes.
Sources: catalog projection, OCI registration, source packages, routes. Examples assume an origin without /v1; no registry request, registration or cloud execution was performed in this documentation pass. Next: HTTP overview, Harness selection.