Providers

Public discovery needs no bearer token and lives outside /v1. Profile and offer management use a signed-in Network account bearer token; Router application API keys cannot manage these resources. Keep account tokens private and use the dashboard for interactive editing.

Discover offers for a model

GET/public/provider-offersPublic · no token required

Query	Type	Meaning
`model`	string · required	Exact model ID, 1–160 characters.
`cursor`	UUID · optional	Previous response's `next_cursor`.

1curl --get "${ROUTER_BASE_URL%/v1}/public/provider-offers" \2  --data-urlencode 'model=gemma3:1b'

Returns { offers, has_more, next_cursor }. Only offers with both profile and offer publication enabled appear. Busy and offline offers can appear alongside available offers.

Read one offer

GET/public/provider-offers/{offer_id}Public · no token required

offer_id is a UUID. Returns one public offer object, or 404 provider_offer_unavailable when it is no longer public. Refresh this endpoint to review a selected offer's current pricing revision.

Public offer fields

Field	Type	Meaning
`offer_id`	UUID	Opaque identifier for the saved computer/model offer.
`model`	string	Exact model ID.
`model_revision`	string	Saved model artifact revision.
`pricing_revision`	integer, at least 1	Current price revision to include in manual selection.
`public_name`	string	Provider-chosen public computer name.
`rates.input`, `rates.output`	decimal strings	Separate USD rates per 1M input/output tokens. Zero is valid.
`availability`	string	`available`, `busy`, or `offline`; an observation, not a reservation.
`provider`	profile object	Published provider identity, described below.

Account IDs, device IDs, and private computer names are excluded. Identity is self-described, and no verified reputation or performance score is supplied.

Read a public profile

GET/public/providers/{handle}Public · no token required

Accepts an optional UUID cursor. Returns { profile, offers, has_more, next_cursor }, including published offers that are offline. A hidden or missing profile returns 404 provider_not_found.

GET/public/providers/{handle}/avatarPublic · no token required

Returns raster image bytes with their image content type while the profile is published. A hidden profile or missing image returns 404 avatar_not_found.

Pagination

Public model discovery, public profile offers, and owner offers return up to 200 offers per page. Pass next_cursor as the next request's cursor; null means the final page. has_more indicates another page. Cursors advance by immutable offer ID; available, busy, and offline offers are sorted in that order within each public page. This is not a price or performance ranking across the full result set.

Read or save your profile

GET/v1/provider-profileBearer token required

Returns { "profile": null } before a profile is saved, otherwise { profile }.

PUT/v1/provider-profileBearer token required

Supply all editable fields; this is not a partial update.

Field	Type	Validation
`display_name`	string	1–80 characters; trimmed, nonblank, no control characters.
`handle`	string	Unique; matches `^[a-z0-9][a-z0-9-]{2,39}$`.
`description`	string	Up to 160 characters; trimmed, no control characters.
`website`	string or null	Optional HTTPS URL up to 300 characters, without credentials; use null to omit.
`published`	boolean	Whether the profile is public.

1curl -X PUT "$ROUTER_BASE_URL/provider-profile" \2  -H "Authorization: Bearer $NETWORK_ACCESS_TOKEN" \3  -H 'Content-Type: application/json' \4  -d '{5    "display_name": "Example Provider",6    "handle": "example-provider",7    "description": "A self-described provider profile.",8    "website": null,9    "published": false10  }'

This example saves a synthetic draft. Returns { profile }. The profile object includes every editable field plus avatar_url (string or null). Owner avatar URLs point to /v1/provider-profile/avatar; public URLs point to /public/providers/{handle}/avatar.

Manage your avatar

POST/v1/provider-profile/avatarBearer token required

Send { "data_url": "data:image/png;base64,..." } with canonical base64 for PNG, JPEG, or WebP. The abbreviated string illustrates the shape; it is not a valid upload. Decoded size is at most 262,144 bytes (256 KiB), and the MIME type must match the image signature. Save a profile first. Send { "data_url": null } to remove the avatar. Returns { profile }.

GET/v1/provider-profile/avatarBearer token required

Returns your image bytes even when the profile is unpublished. Both image-read endpoints send X-Content-Type-Options: nosniff; a missing avatar returns 404 avatar_not_found.

List or publish your offers

GET/v1/provider-offersBearer token required

Accepts an optional UUID cursor. Returns { offers, has_more, next_cursor }, including unpublished saved-price offers. Owner offers include offer_id, device_id, model, model_revision, pricing_revision, public_name, published, rates, availability, and needs_review. needs_review indicates that the saved model revision no longer matches an enabled edition. There is no nested public provider object in owner offers.

PUT/v1/provider-offers/{offer_id}Bearer token required

Send { "public_name": "Example computer", "published": true }. public_name is required, 1–60 characters, trimmed, nonblank, without control characters. The UUID must identify your own saved offer. Returns the refreshed first page of owner offers, not one offer object. Save a profile before publishing an offer. New offers start unpublished.

Both the profile and individual offer must be published for public discovery and new manual requests. Unpublishing the profile retains individual publication flags; republishing restores flagged offers. Publication does not change Serving or Auto eligibility. Already accepted requests retain their saved quotes.

Errors and selection

Status	Code	Meaning
400	`invalid_profile`, `invalid_website`, `invalid_offer_name`, or `invalid_avatar`	Correct the submitted details or image. Schema validation can also reject missing or unknown fields.
401	`auth_no_token` or another authentication error	Supply a valid signed-in Network account bearer token.
403	`api_key_scope`	Use your signed-in Network account for owner management.
409	`provider_handle_taken`	Choose another unique handle.
409	`profile_required`	Save a profile before publishing an offer or managing its avatar.
404	`offer_not_found`	No owned saved offer matches the supplied ID.
404	`provider_not_found`, `provider_offer_unavailable`, or `avatar_not_found`	The public resource is hidden or missing, or no avatar is saved.
429	Rate limit	Respect retry guidance and bound polling or writes.
503	`provider_profiles_unavailable`	Profile storage is temporarily unavailable; do not treat this as an empty result.

Use { offer_id, pricing_revision } in the chat body's provider_selection to choose an offer. See choosing a provider for Auto, manual selection, spending limits, and recovery, and chat completions for request headers and selection errors.