Skip to main content
Use the supplier API to enroll servers, track your nodes and the VMs running on them, read telemetry, submit listings, and take nodes back from your own tools. It is the same API the supplier portal uses. Supplier approval also approves your organization to buy compute, including through Reserve, without a separate buyer approval. To return to the customer console, open the account menu in the supplier portal’s top toolbar and select Go to Compute. If supplier access is removed, your organization’s buyer approval stays unchanged. Supplier routes require current supplier access. Contact Ornn to restore it. If your supply request is not approved, the portal shows Not approved. Contact Ornn to request another review; submitting the same request again does not reopen it.

Authenticate

In the supplier portal, open API keys in the sidebar and select Create key. Enter a name, choose the supplier organization the key belongs to and its Access, and create the key. Copy it before selecting Done; it is only shown once. Send it as a bearer token to https://api.ornn.com. Choose Read only for tools that only read, such as syncing your nodes, listings, reservations, and ledger entries into your own systems. A read-only key can make GET requests and read current telemetry with POST /v1/observability/nodes/telemetry/latest; every other request, including enrollment, listing changes, and taking a node back, returns 403 with code api_key_read_only. Choose Read and write for tools that change anything. The Developer quickstart banner above the API keys list shows a copyable request. Your API base URL and organization ID appear underneath with copy controls. Choose a request from Code example above the snippet to update and copy a curl example for authentication, inventory, telemetry, enrollment, listing submission, or node preemption. Choose Preempt a node to take a listed node back, and read its prerequisites and response guidance before running the command. See Take a node back for details. Replace the placeholders before running a command in your terminal.
The key belongs to the organization you created it in, not to you, so it keeps working if you leave and you don’t need an organization header. The response lists that one organization; its id is your organization ID. Supplier routes require that organization to be a supplier. See API keys to create, revoke, and secure keys.

Routes

De-enroll a node

In the supplier portal, open Nodes, select a node, and choose De-enroll node. The confirmation reminds you that this won’t wipe the node. If the button is disabled, hover over it to see why. Remove the node from its listing first, and wait until it has no reservation or remaining VMs. Removing the last node from a listing withdraws that listing. Your tools can call POST /v1/orchestrator/nodes/{node_id}/terminate with the same authentication as other supplier requests. Only nodes owned by your organization can be de-enrolled. The response contains node_id, status and deleted. De-enrollment does not shut down the server, uninstall its agent, or wipe its disks. If a request fails, read detail.message and retry after resolving the issue.

Nodes and VMs

The node list returns nodes and, when there are more, next_cursor. Send that cursor unchanged on the same path until it is null.
VM reads only work for nodes your organization owns. They return operational fields only, never renter details.

Telemetry

The batch read accepts node_ids, virtual_machine_ids, or both, up to 5,000 IDs in total.
History reads take ISO start and end timestamps, a comma-separated metrics list, and max_points from 1 to 500. Available metrics are gpu_temperature, gpu_utilization, cpu_utilization, cpu_temperature, and memory_utilization. The response contains windows, each with metric, start, end, mean, min, and max.
Poll current readings every 20–30 seconds. On a 429, wait for the Retry-After interval before retrying.

Enrollment

Create an enrollment command with your organization ID:
The response contains id, install_command and credential_expires_at. Running it on a server enrolls that server with Ornn and changes the machine, so treat it as a deliberate step rather than an automated retry. Track progress with GET /v1/orchestrator/enrollment/configurable/runs/{id}/hosts. Read each host’s steps at /v1/orchestrator/enrollment/configurable/hosts/{id}/steps and live output at /v1/orchestrator/enrollment/configurable/hosts/{id}/events. Use a saved setup by adding profile_id to command creation; omitting it selects Standard. In the supplier portal, Edit enrollment configuration is described in Enroll a host. Previously issued commands keep their original settings. Enrollment uses the connection saved on the selected profile. Standard enrollment uses Direct SSH. A configured private connection requires its gateway to exist before command creation; contact Ornn if it is unavailable. A new attempt on the same server automatically cancels an earlier blocked attempt for your organization when no step is still executing. The earlier attempt keeps its history but cannot resume. If enrollment is actively running, wait for it to finish before starting another attempt. Standard enrollment attempts recovery snapshot capture when available. Saved profiles can also enable capture; it is off when omitted from a profile. Capture requires prepared recovery media and permission to reboot; enrollment resumes after the offline capture. Newly issued commands report a warning and continue without a snapshot when capture is unavailable or reboot is not permitted. Previously issued commands retain their original capture behavior. A captured image still needs review before it can be used for restoration.

Saved connection configurations

You can save multiple named connection configurations for your organization using the API. This backend inventory currently supports netbird and reverse_ssh. It is not yet selectable during enrollment. Saving a configuration does not create a gateway or change existing network settings. For example, create a reverse-SSH configuration with {"name":"Private facility","kind":"reverse_ssh"}. Your authenticated organization owns it; you do not need to supply its ID. Names are unique within your organization. List responses contain configs and next_cursor; pass the cursor as after to continue, with limit between 1 and 100. NetBird configurations require netbird_management_url, netbird_setup_key_secret_ref, and netbird_version. The secret field must reference an existing, explicitly numbered Secret Manager version. Contact Ornn to arrange that reference; never send the setup key itself. Saving the reference does not verify its contents or access permissions. PATCH preserves omitted fields and clears nullable fields when you send null. It also accepts disabled: true or false. A type change must leave a valid combination of fields. Configuration changes do not alter issued enrollment commands.

Create a connection gateway

When gateway creation is enabled for your organization, call POST /v1/orchestrator/supplier-gateways with {"connection_config_id":"YOUR_CONFIG_ID"}. The configuration must be enabled. You do not supply cloud placement or credentials in this request. Responses include your gateway’s ID, public IP, SSH host public key, timestamps and creation status. Internal cloud placement and infrastructure identifiers are omitted. The response includes the gateway id and creation_status. Read it with GET /v1/orchestrator/supplier-gateways/{id}. A 202 response means creation is in progress. Repeated requests reuse the same active creation attempt or return the existing gateway. A failed attempt is not retried automatically by another ordinary POST; send the same configuration ID with "retry":true to request a new attempt. Display error_message for failures. ready confirms that the gateway connection has been configured. It does not enroll a node or publish customer SSH forwarding. Creation history may later become unavailable (unknown) while the gateway continues running. Recovery from unknown requires retry:true, including when an earlier attempt never recorded an IP. Gateway creation currently has no console flow or deletion API.

Listing fee

GET /v1/markets/fees returns the transaction fee as transactionSpreadPpm, in parts per million. Your take-home per GPU-hour (or vCPU-hour on CPU listings) is your price minus the fee amount: price × transactionSpreadPpm / 1,000,000, rounded half up to the micro-dollar. The fee in force when a reservation is created is frozen on it. Submissions omit expectedFeePpm.

List enrolled nodes for review

Send a POST to /commerce/v2/listings with an Idempotency-Key header. Reuse the same key when you retry the same submission. One listing can offer several enrolled nodes.
  • nodeIds lists up to 64 nodes. They must be enrolled and not terminated, and share a facility and hardware: GPU inventory with the same GPU model and GPU count, or CPU nodes (no GPUs) with the same number of whole cores, at least one (2 vCPUs). Hardware, location and node count come from enrollment, so you don’t send them. A CPU listing offers each node’s cores (its vCPUs over two, rounded down) as coresPerNode; each core is 2 vCPUs. CPU nodes with different core counts need separate listings.
  • proposal.supplierPricePerGpuHour is your listing price in USD per GPU-hour, or per vCPU-hour on CPU listings, as a decimal string with up to six decimal places and a minimum of 0.01.
  • availableAt and availableUntil are ISO timestamps in whole seconds.
The response contains the new listing (state proposed) and its terms. Read terms with GET /commerce/v2/listings/{id}/terms and attached node IDs with GET /commerce/v2/listings/{id}/nodes. Selected nodes belong exclusively to the listing while it awaits review; they cannot be offered on another listing. Approval keeps the same listing and term IDs. Rejection or withdrawal releases the selected nodes. Edit a proposed or rejected listing with PATCH /commerce/v2/listings/{id}, sending the same fields; no revision token is required. You can replace its node selection before approval. Resubmission validates and claims the nodes again. After an unconfirmed create, refresh your listings before submitting again to avoid creating a duplicate. Published listings remain read-only in the submission form. Listing conversations are no longer available. After approval, use the same PATCH route with only notes and/or documents to update private additional details and add attachments. An empty notes string clears it; omitted fields remain unchanged. Send the full attachment list, including every saved file; existing attachments cannot be removed. Files must come from your organization’s uploads. Refresh and retry if another save added a file. These updates preserve publication status and agreed customer terms. Keep them separate from proposal, node, or commercial changes. Update an advertised price after approval with PATCH /commerce/v2/listings/{id}/terms/{termId}, an Idempotency-Key, and only {"pricePerGpuHourMicroUsd": 1750000} (for example, $1.75 per GPU-hour, or per vCPU-hour for CPU capacity). This applies to your own primary and secondary listings. Other financial fields cannot be included. Existing purchases retain their agreed price, including future bookings. Reuse the same key when retrying the same price change; use a new key for a different price. Include expectedPricePerGpuHourMicroUsd with the current price to reject stale edits. If an older reservation is missing saved rates, contact Ornn before changing that term’s price. Withdraw a listing with POST /commerce/v2/listings/{id}/delist, subject to its existing reservation and preemption-notice restrictions. To publish withdrawn supplier capacity again, contact Ornn. Setting its state to available, directly or through Draft, does not restore publication with your organization credentials. Listings backed by your own reservations follow the relisting rules.

Take a node back

Send a DELETE for the node on its listing. The node stops selling through that listing at once.
  • 204 means no customer VMs were running, so the node is removed now.
  • 202 returns { "nodeId", "removesAt" }. Customers with VMs on the node get your preemption notice by email and inside their VMs, and their VMs stop when it runs out. removesAt is the earliest removal time; VM shutdown and cleanup can take longer. You get an email when the node is free.
  • 409 means the node can’t be removed yet, for example while a Reserved booking holds it. Show detail.message.
Retrying is safe. A repeated request keeps the original removesAt and does not notify customers again. Before you preempt, GET /commerce/v2/listings/{id}/nodes lists each node in nodes with preemptNoticeSeconds, the longest notice owed to the VMs this listing sold on it. During a preemption, the node also shows preemptRequestedAt and removesAt. A removed node leaves the list. Removing the last node withdraws a published listing. To sell a removed node again, create a new listing for it. On a proposed or rejected listing, the same DELETE removes the node from your selection right away; keep at least one node attached. See Spot listings and taking a node back for what customers see.

Facilities for manual capacity offers

List your facilities with GET /commerce/facilities?owned=true using your selected organization; each facility’s region is one of Ornn’s locations, such as us-west-3 (“US West 3”). List the locations with GET /v1/orchestrator/locality/regions (facility_slug, facility_name). For a manual offer, send either facilityId or proposal.region: "us-west-3". A location you have no facility at yet is added with the offer and returned as the listing’s facilityId; reuse that ID for subsequent edits or offers. Any other region is refused with 422 unknown_location. An existing facility must belong to your selected organization. Enrolled-node offers use the facility recorded during enrollment.