providers

Declare Provider Version

Declare a provider version from what its wheel claims about itself.

The wheel’s pragma.provider entry point names the provider in the caller’s organization. The version is recorded as awaiting_wheel; upload its wheel to PUT /providers/publish/{operation_id}/wheel with the returned operation_id, then poll the version until it is published or failed, where error_message says why.

Returns: The version with its operation_id, awaiting_wheel until its wheel is uploaded.

POST

providers

publish

Declare Provider Version

curl --request POST \
  --url https://api.example.com/providers/publish \
  --header 'Content-Type: application/json' \
  --data '
{
  "wheel_filename": "<string>",
  "wheel_sha256": "<string>",
  "wheel_size": 123,
  "dist_info_directory": "<string>",
  "metadata": "aSDinaTvuI8gbWludGxpZnk=",
  "entry_points": "aSDinaTvuI8gbWludGxpZnk=",
  "changelog": "<string>"
}
'

import requests

url = "https://api.example.com/providers/publish"

payload = {
    "wheel_filename": "<string>",
    "wheel_sha256": "<string>",
    "wheel_size": 123,
    "dist_info_directory": "<string>",
    "metadata": "aSDinaTvuI8gbWludGxpZnk=",
    "entry_points": "aSDinaTvuI8gbWludGxpZnk=",
    "changelog": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    wheel_filename: '<string>',
    wheel_sha256: '<string>',
    wheel_size: 123,
    dist_info_directory: '<string>',
    metadata: 'aSDinaTvuI8gbWludGxpZnk=',
    entry_points: 'aSDinaTvuI8gbWludGxpZnk=',
    changelog: '<string>'
  })
};

fetch('https://api.example.com/providers/publish', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'wheel_filename' => '<string>',
    'wheel_sha256' => '<string>',
    'wheel_size' => 123,
    'dist_info_directory' => '<string>',
    'metadata' => 'aSDinaTvuI8gbWludGxpZnk=',
    'entry_points' => 'aSDinaTvuI8gbWludGxpZnk=',
    'changelog' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.example.com/providers/publish"

	payload := strings.NewReader("{\n  \"wheel_filename\": \"<string>\",\n  \"wheel_sha256\": \"<string>\",\n  \"wheel_size\": 123,\n  \"dist_info_directory\": \"<string>\",\n  \"metadata\": \"aSDinaTvuI8gbWludGxpZnk=\",\n  \"entry_points\": \"aSDinaTvuI8gbWludGxpZnk=\",\n  \"changelog\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/providers/publish")
  .header("Content-Type", "application/json")
  .body("{\n  \"wheel_filename\": \"<string>\",\n  \"wheel_sha256\": \"<string>\",\n  \"wheel_size\": 123,\n  \"dist_info_directory\": \"<string>\",\n  \"metadata\": \"aSDinaTvuI8gbWludGxpZnk=\",\n  \"entry_points\": \"aSDinaTvuI8gbWludGxpZnk=\",\n  \"changelog\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/providers/publish")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"wheel_filename\": \"<string>\",\n  \"wheel_sha256\": \"<string>\",\n  \"wheel_size\": 123,\n  \"dist_info_directory\": \"<string>\",\n  \"metadata\": \"aSDinaTvuI8gbWludGxpZnk=\",\n  \"entry_points\": \"aSDinaTvuI8gbWludGxpZnk=\",\n  \"changelog\": \"<string>\"\n}"

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

{
  "prefix": "<string>",
  "name": "<string>",
  "version": "<string>",
  "distribution_name": "<string>",
  "operation_id": "<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>",
  "operation_id": "<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>"
}

Body

application/json

What a provider wheel claims about itself, declared before it is uploaded.

metadata and entry_points arrive as base64 text and hold the decoded bytes. The wheel uploaded afterwards must match the declaration.

Attributes: wheel_filename: Filename of the built wheel. wheel_sha256: Lowercase hex SHA-256 digest of the wheel file. wheel_size: Size of the wheel file in bytes. dist_info_directory: Name of the wheel's .dist-info directory, such as postgresql-1.0.0.dist-info. metadata: Contents of the wheel's METADATA file. entry_points: Contents of the wheel's entry_points.txt, or None when the wheel has none. changelog: Release notes for the version, or None.

wheel_filename

string

required

Required string length: 1 - 255

wheel_sha256

string

required

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

wheel_size

integer

required

dist_info_directory

string

required

Required string length: 1 - 255

metadata

file

required

Base64 text of the wheel's METADATA file, at most 4 MiB once decoded.

Maximum string length: 5592408

entry_points

file | null

Base64 text of the wheel's entry_points.txt file, at most 4 MiB once decoded.

Maximum string length: 5592408

changelog

string | null

Maximum string length: 65536

Response

Admission of the same declaration has not finished; its version is returned.

A provider version as its publish declaration returns it.

Only the declaration response carries operation_id; every other response leaves it out.

Attributes: operation_id: Publish operation the version's wheel is uploaded to, at PUT /providers/publish/{operation_id}/wheel.

prefix

string

required

name

string

required

version

string

required

distribution_name

string

required

Required string length: 1 - 200

operation_id

string

required

Minimum string length: 1

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

Declare Provider Version

curl --request POST \
  --url https://api.example.com/providers/publish \
  --header 'Content-Type: application/json' \
  --data '
{
  "wheel_filename": "<string>",
  "wheel_sha256": "<string>",
  "wheel_size": 123,
  "dist_info_directory": "<string>",
  "metadata": "aSDinaTvuI8gbWludGxpZnk=",
  "entry_points": "aSDinaTvuI8gbWludGxpZnk=",
  "changelog": "<string>"
}
'

import requests

url = "https://api.example.com/providers/publish"

payload = {
    "wheel_filename": "<string>",
    "wheel_sha256": "<string>",
    "wheel_size": 123,
    "dist_info_directory": "<string>",
    "metadata": "aSDinaTvuI8gbWludGxpZnk=",
    "entry_points": "aSDinaTvuI8gbWludGxpZnk=",
    "changelog": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    wheel_filename: '<string>',
    wheel_sha256: '<string>',
    wheel_size: 123,
    dist_info_directory: '<string>',
    metadata: 'aSDinaTvuI8gbWludGxpZnk=',
    entry_points: 'aSDinaTvuI8gbWludGxpZnk=',
    changelog: '<string>'
  })
};

fetch('https://api.example.com/providers/publish', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'wheel_filename' => '<string>',
    'wheel_sha256' => '<string>',
    'wheel_size' => 123,
    'dist_info_directory' => '<string>',
    'metadata' => 'aSDinaTvuI8gbWludGxpZnk=',
    'entry_points' => 'aSDinaTvuI8gbWludGxpZnk=',
    'changelog' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.example.com/providers/publish"

	payload := strings.NewReader("{\n  \"wheel_filename\": \"<string>\",\n  \"wheel_sha256\": \"<string>\",\n  \"wheel_size\": 123,\n  \"dist_info_directory\": \"<string>\",\n  \"metadata\": \"aSDinaTvuI8gbWludGxpZnk=\",\n  \"entry_points\": \"aSDinaTvuI8gbWludGxpZnk=\",\n  \"changelog\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/providers/publish")
  .header("Content-Type", "application/json")
  .body("{\n  \"wheel_filename\": \"<string>\",\n  \"wheel_sha256\": \"<string>\",\n  \"wheel_size\": 123,\n  \"dist_info_directory\": \"<string>\",\n  \"metadata\": \"aSDinaTvuI8gbWludGxpZnk=\",\n  \"entry_points\": \"aSDinaTvuI8gbWludGxpZnk=\",\n  \"changelog\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/providers/publish")

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"wheel_filename\": \"<string>\",\n  \"wheel_sha256\": \"<string>\",\n  \"wheel_size\": 123,\n  \"dist_info_directory\": \"<string>\",\n  \"metadata\": \"aSDinaTvuI8gbWludGxpZnk=\",\n  \"entry_points\": \"aSDinaTvuI8gbWludGxpZnk=\",\n  \"changelog\": \"<string>\"\n}"

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

{
  "prefix": "<string>",
  "name": "<string>",
  "version": "<string>",
  "distribution_name": "<string>",
  "operation_id": "<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>",
  "operation_id": "<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

Declare Provider Version

Body

Response