The Evolution of API Write-Safety: Deep Dive into the Kin Score “Upsert” Facet

In the rapidly maturing landscape of the API economy, the ability to read data has long been commoditized. However, the ability to safely, reliably, and idempotently write data remains a significant hurdle for developers and autonomous agents alike. As part of an ongoing series detailing the Kin Score—a metric designed to quantify the quality and transparency of API providers—we turn our attention to the seventh of nine essential facets: Create-or-Update Ergonomics (Upsert).

This facet, introduced in version 0.20.0 on September 7th, represents a critical shift in how we evaluate API reliability. It poses a singular, high-stakes question to providers: If your API accepts write operations, can a caller create or update a record in a single request, keyed on an identifier they already hold, and—crucially—receive confirmation of which action occurred?

The Philosophical Shift: Moving Beyond Basic Contractual Compliance

Historically, API rubrics have focused heavily on "contractual" transparency—whether an API is documented and callable. While essential, these metrics often ignored the "Day Two" operational realities of software engineering. Developers frequently encounter a common failure pattern: in the absence of an upsert mechanism, a system must first perform a GET (search) to check for existence, followed by a branch into either a POST (create) or a PUT/PATCH (update).

The inherent danger in this two-step dance is the race condition. If a network blip, a timeout, or a logic error causes a developer to skip the search phase, the system risks creating a duplicate record. According to roadmap data from the 0.20.0 release, a staggering 82.8% of write-accepting providers found themselves in this precarious position, relying on the caller to manage state synchronization manually.

The Upsert facet was designed to address this. It isn’t merely about feature availability; it is the first facet in the Kin Score rubric that explicitly asks whether an API is "safe to call twice."

Chronology: The Development of the Upsert Facet

The journey to the current 0.23 iteration of the Kin Score has been defined by a methodical approach to API evaluation.

• Pre-0.20.0 (The Foundation): The focus remained on general operational transparency. Write-safety was treated as an secondary concern, often conflated with basic RESTful CRUD compliance.
• September 7, 2026 (The 0.20.0 Release): The Upsert facet was officially introduced. It brought 36 points of scoring potential spread across four distinct checks. The team explicitly chose to price these points based on the commitment required from the provider rather than the prevalence of the feature in the wild.
• October 2026 (The 0.23.0 Maturity): By the time of the 0.23 release, the facet had stabilized. The rules regarding how a provider is penalized—or rewarded—for their write ergonomics were refined to ensure that providers are judged against the "observed mean" rather than an arbitrary ideal, preventing the facet from becoming a punitive measure for the entire catalog.

Supporting Data: Understanding the "Observed Mean"

One of the most nuanced aspects of the Kin Score is the handling of conditional facets. The Upsert facet is strictly applicable only to providers that accept writes. A weather service or a static reference dataset cannot, by definition, "upsert" data. Applying a score of zero to such providers would be a statistical error, unfairly penalizing them for capabilities they were never intended to possess.

When the facet launched, the catalog comprised 7,955 providers with parseable first-party contracts. Of those, 1,125 were read-only, leaving 6,803 as "scorable." To prevent a "mass-penalty" effect—where thousands of providers would lose points for a feature that was then nascent—the scoring was re-centered on the observed mean of 7.06.

This mechanism ensures that a provider meeting the industry standard remains neutral, while those leading the way gain points and those trailing behind lose only a marginal amount. This is a deliberate "regulatory correction" intended to encourage upward mobility without destabilizing the overall ecosystem rankings.

The Mechanics of the "Upsert" Claim

The Kin Score facet evaluates three specific commitments:

1. Naming: Does the provider explicitly label the operation as an upsert? This is viewed as a clear claim of intent.
2. Keying: Does the provider accept the caller’s identifier as the primary key for the write? This is a fundamental commitment to idempotency.
3. Discriminator Reporting: Does the response explicitly indicate which branch (create or update) was executed?

Notably, the scoring team made a conscious decision to ignore documented "200 vs. 201" status code splits. While some developers rely on 201 (Created) vs. 200 (OK/Updated) to distinguish outcomes, this practice is too noisy. With 569 providers potentially using status codes for unrelated reasons, the team opted for a higher bar: a formal, documented discriminator field. If it isn’t in the contract, it scores nothing.

Implications for Autonomous Agents

The rise of autonomous AI agents has brought the issue of write-safety to the forefront. Unlike human-driven interfaces, agents act in cycles. If a request times out, an agent cannot "guess" whether the write succeeded or failed. If it retries, it risks data corruption via duplication.

In the context of "Agent Readiness," the Upsert facet is a prerequisite. A plain POST create is the enemy of agentic workflows. An upsert keyed on a natural identifier ensures that the retry lands on the same record, and a discriminator in the response allows the agent to log the outcome accurately without requiring a redundant "check" request.

As we look toward the future, this facet sits alongside the idempotency check. While an idempotency key protects a single request, a natural-key upsert protects the integrity of the database record itself.

Current Landscape: HubSpot, Salesforce, and Beyond

In the current catalog, we see a wide variance in adoption. HubSpot serves as the gold standard for this facet, boasting a perfect 100.0 score. Its POST /crm/objects/version/contacts/batch/upsert endpoint acts as the reference implementation for the Kin Score logic. Salesforce, while robust, scores 72.2, reflecting a different approach to object management.

However, these figures must be interpreted with caution. The Kin Score relies on contract analysis. If an API provider offers a stellar upsert capability but buries the implementation details in a help article rather than exposing them in the OpenAPI or machine-readable contract, the facet will treat it as non-existent. The goal is not just to build better APIs, but to ensure that those capabilities are discoverable by the machines that consume them.

Official Guidance and Future Directions

For providers looking to improve their standing, the path is clear:

1. Standardize the Endpoint: Adopt clear naming conventions (e.g., upsert).
2. Explicitly Define Keys: Document the identifiers used for upsert logic.
3. Formalize the Response: Include a metadata field in the response body that confirms the operation outcome (e.g., "status": "created").
4. Audit the Contract: Ensure that the OpenAPI definition matches the actual behavior, as machine-readable contracts are the source of truth for the Kin Score.

The roadmap for the Kin Score indicates that while we have opened the "write-safety gap" with this release, there is more work to be done. Future iterations will likely incorporate If-Match headers, ETags, and more granular retry semantics. For now, the 0.23 release remains focused on the fundamentals of "Create-or-Update" ergonomics.

As the industry moves toward a more automated, agent-first architecture, the ability to safely write data will define the winners of the next decade. Providers that prioritize the ergonomics of their write operations are not just simplifying life for developers—they are building the infrastructure that will power the next generation of autonomous digital agents.

Tomorrow, we will explore the "Open Source Surface" facet, continuing our series on building a more transparent and interoperable API economy.