providers

Upload Provider Wheel

Upload the wheel of a declared provider version.

The request body is the wheel file declared by POST /providers/publish. Once accepted, the version is admitted on the organization’s provider host; poll it until it is published or failed, where error_message says why. While the platform is taking as many wheels as it can, the upload is refused with 503 and the version is unchanged; upload it again after Retry-After.

Returns: The version; when this upload is accepted, staged or further along its admission.

PUT

providers

publish

{operation_id}

wheel

Upload Provider Wheel

curl --request PUT \
  --url https://api.example.com/providers/publish/{operation_id}/wheel

const options = {method: 'PUT'};

fetch('https://api.example.com/providers/publish/{operation_id}/wheel', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/providers/publish/{operation_id}/wheel",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/providers/publish/{operation_id}/wheel"

	req, _ := http.NewRequest("PUT", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/providers/publish/{operation_id}/wheel")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body

{
  "prefix": "<string>",
  "name": "<string>",
  "version": "<string>",
  "distribution_name": "<string>",
  "canonical": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "wheel_filename": "<string>",
  "wheel_sha256": "<string>",
  "package": "<string>",
  "summary": "<string>",
  "keywords": [
    "<string>"
  ],
  "schemas": [
    {}
  ],
  "python_version": "<string>",
  "sdk_version": "<string>",
  "protocol_versions": [
    123
  ],
  "embedded_providers": {},
  "operation_deadline_at": "2023-11-07T05:31:56Z",
  "changelog": "<string>",
  "status": "awaiting_wheel",
  "published_at": "2023-11-07T05:31:56Z",
  "failure_category": "wheel_refused",
  "error_message": "<string>"
}

{
  "prefix": "<string>",
  "name": "<string>",
  "version": "<string>",
  "distribution_name": "<string>",
  "canonical": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "wheel_filename": "<string>",
  "wheel_sha256": "<string>",
  "package": "<string>",
  "summary": "<string>",
  "keywords": [
    "<string>"
  ],
  "schemas": [
    {}
  ],
  "python_version": "<string>",
  "sdk_version": "<string>",
  "protocol_versions": [
    123
  ],
  "embedded_providers": {},
  "operation_deadline_at": "2023-11-07T05:31:56Z",
  "changelog": "<string>",
  "status": "awaiting_wheel",
  "published_at": "2023-11-07T05:31:56Z",
  "failure_category": "wheel_refused",
  "error_message": "<string>"
}

Path Parameters

operation_id

string<uuid>

required

Response

The wheel was already uploaded by an earlier request; nothing is stored and the version is returned as it stands.

One version of a provider, from upload through admission.

The declaration fields, admission inputs, organization_id, stream_sequence, operation_id, lock, pyproject and operation_type are stored but never serialized.

Identity fields (frozen): prefix: Namespace token of the owning provider. name: Provider short name this version belongs to. version: Semantic version string (e.g., "1.0.0").

Wheel: wheel_filename: Filename of the wheel as renamed to the owner's distribution name; the registry stores the wheel under it. wheel_sha256: SHA-256 digest of the wheel bytes as renamed to the owner's distribution name; None until staged. distribution_name: Wheel distribution name the version is published under, <prefix>-<name> canonicalized. package: Importable package that holds the provider. summary: Core-metadata summary of the wheel, used as the catalog description when the version creates the provider. keywords: Core-metadata keywords of the wheel, used as the catalog tags when the version creates the provider.

Declaration: declared_sha256: SHA-256 digest of the wheel as built, before the rename; the upload must match it. declared_size: Size in bytes of the wheel as built. declared_dist_info_sha256: SHA-256 digest over the declared METADATA and entry_points.txt bytes, each prefixed with its length; the uploaded wheel's files must match it. dist_info_directory: Declared name of the wheel's .dist-info directory.

Admission inputs: organization_id: Organization that declared the version. requires_python: Normalized Requires-Python specifier of the wheel, or None when it declares none. registry_pins: Canonical distribution names the version resolves only from the Pragmatiks registry, computed at publish. declared_embeds: Canonical distribution names the wheel declares under pragma.embeds.

Admission results: schemas: Resource type schemas reported by introspection, each keyed on "resource". python_version: Exact Python ("3.14.2") the version was admitted on and installs on. pyproject: pyproject.toml text admission locked, which the version installs from with its lock. lock: Resolved uv.lock text the version installs from. sdk_version: Pragmatiks SDK version the lock resolved. protocol_versions: Host protocol versions the provider speaks. embedded_providers: Pragmatiks providers the version installs, distribution name to locked version.

Operation (system-managed): operation_id: Publish operation in flight, issued at declaration; the wheel is uploaded to it, and every later write must match it. operation_type: Kind of operation in flight, always publish. operation_deadline_at: When the admission must finish; set when the provider host first takes it. stream_sequence: Sequence of the admission request message the provider host took, recorded at admitting.

State (system-managed): changelog: Release notes supplied at publish. status: Publish lifecycle status. published_at: Timestamp when the version was published. failure_category: Why admission failed, when failed. error_message: User-facing failure message, when failed.

prefix

string

required

name

string

required

version

string

required

distribution_name

string

required

Required string length: 1 - 200

canonical

string

required

read-only

Slash-joined prefix/name canonical string of the owning provider.

Returns: Display form of the provider identity this version belongs to.

created_at

string<date-time>

updated_at

string<date-time>

wheel_filename

string | null

Minimum string length: 1

wheel_sha256

string | null

Pattern: ^[0-9a-f]{64}$

package

string | null

summary

string | null

keywords

string[]

schemas

Schemas · object[] | null

python_version

string | null

sdk_version

string | null

protocol_versions

integer[]

embedded_providers

Embedded Providers · object

Show child attributes

operation_deadline_at

string<date-time> | null

changelog

string | null

status

enum<string>

default:awaiting_wheel

Publish lifecycle status for a provider version.

A declared version is awaiting_wheel until its wheel is uploaded, then staged, queued for the organization's provider host, admitting while the host admits it, and promoting while the admitted wheel is copied to the registry. It ends published (terminal) or failed; a failed version may be published again under the same version number.

Available options:

awaiting_wheel,

staged,

queued,

admitting,

promoting,

published,

failed

published_at

string<date-time> | null

failure_category

enum<string> | null

Why a provider version failed admission.

Available options:

wheel_refused,

wheel_lost,

digest_mismatch,

python_unavailable,

dependency_resolution_failed,

undeclared_embedded_provider,

unregistered_embedded_provider,

embedded_provider_not_depended_on,

unsupported_protocol,

import_failed,

missing_observe,

stored_wheel_conflict,

deadline_exceeded,

platform_error,

organization_deleted

error_message

string | null

Upload Provider Wheel

curl --request PUT \
  --url https://api.example.com/providers/publish/{operation_id}/wheel

const options = {method: 'PUT'};

fetch('https://api.example.com/providers/publish/{operation_id}/wheel', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/providers/publish/{operation_id}/wheel",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/providers/publish/{operation_id}/wheel"

	req, _ := http.NewRequest("PUT", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/providers/publish/{operation_id}/wheel")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body

{
  "prefix": "<string>",
  "name": "<string>",
  "version": "<string>",
  "distribution_name": "<string>",
  "canonical": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "wheel_filename": "<string>",
  "wheel_sha256": "<string>",
  "package": "<string>",
  "summary": "<string>",
  "keywords": [
    "<string>"
  ],
  "schemas": [
    {}
  ],
  "python_version": "<string>",
  "sdk_version": "<string>",
  "protocol_versions": [
    123
  ],
  "embedded_providers": {},
  "operation_deadline_at": "2023-11-07T05:31:56Z",
  "changelog": "<string>",
  "status": "awaiting_wheel",
  "published_at": "2023-11-07T05:31:56Z",
  "failure_category": "wheel_refused",
  "error_message": "<string>"
}

{
  "prefix": "<string>",
  "name": "<string>",
  "version": "<string>",
  "distribution_name": "<string>",
  "canonical": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "wheel_filename": "<string>",
  "wheel_sha256": "<string>",
  "package": "<string>",
  "summary": "<string>",
  "keywords": [
    "<string>"
  ],
  "schemas": [
    {}
  ],
  "python_version": "<string>",
  "sdk_version": "<string>",
  "protocol_versions": [
    123
  ],
  "embedded_providers": {},
  "operation_deadline_at": "2023-11-07T05:31:56Z",
  "changelog": "<string>",
  "status": "awaiting_wheel",
  "published_at": "2023-11-07T05:31:56Z",
  "failure_category": "wheel_refused",
  "error_message": "<string>"
}

Overview

API Reference

api-keys

auth

canvas

events

graph

files

ops

organizations

patches

projects

providers

resources

webhooks

Upload Provider Wheel

Path Parameters

Response