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 tohttps://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.
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 callPOST /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 returnsnodes and, when there are more, next_cursor. Send that cursor unchanged on the same path until it is null.
Telemetry
The batch read acceptsnode_ids, virtual_machine_ids, or both, up to 5,000 IDs in total.
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.
429, wait for the Retry-After interval before retrying.
Enrollment
Create an enrollment command with your organization ID: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 supportsnetbird 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, callPOST /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 aPOST 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.
nodeIdslists 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) ascoresPerNode; each core is 2 vCPUs. CPU nodes with different core counts need separate listings.proposal.supplierPricePerGpuHouris 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 of0.01.availableAtandavailableUntilare ISO timestamps in whole seconds.
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 aDELETE for the node on its listing. The node stops selling through that listing at once.
204means no customer VMs were running, so the node is removed now.202returns{ "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.removesAtis the earliest removal time; VM shutdown and cleanup can take longer. You get an email when the node is free.409means the node can’t be removed yet, for example while a Reserved booking holds it. Showdetail.message.
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 withGET /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.