Add one key's vendor price, now or from a later instant

POST /v1/platform/vendor-prices

Property	Value
Operation	`add_vendor_price`
Group	Platform
Scope	`platform:write`
Route class	`control`
Idempotency	`Idempotency-Key` accepted: a retry with the same key replays the first answer
Audit	Audited `platform.price.add` (mutation)
Released in	1.38.0
Phase 0 host	Served (the hosted api pins 1.65.0)

Writes one row per unit of the entry in one transaction (1.38.0), with origin operator, the caller as entered_by, and the Audit event platform.price.add, which records the ids, the Provider, the stage, the model, the units, effective_from and the ids it replaced. An entry whose effective_from is later than now is upcoming and takes effect at that instant with no deploy; an entry with the key and effective_from of an upcoming row replaces it, and one with those of a row in force or ended is refused. Refused with validation_failed: a price not above 0 (price_not_positive), an effective_from before the transaction's instant (price_effective_in_past), a price above price_ceiling_factor times the highest price in force of its unit (price_above_ceiling), a replacement of a row in force or ended (price_not_replaceable), and a Provider and chain stage the catalog does not serve (provider_not_allowed, reason stage_not_served). A refused entry writes no row.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the platform:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl -X POST "$VOCAL_API/v1/platform/vendor-prices" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "mock",
    "stage": "stt",
    "model": "<model>",
    "units": [
      {
        "unit": "audio_minute",
        "unit_price_micros": 1
      }
    ],
    "source": {
      "url": "https://example.test/a",
      "read_at": "<read_at>"
    },
    "source_figure": "<source_figure>",
    "verified": false
  }'

const response = await fetch(`${process.env.VOCAL_API}/v1/platform/vendor-prices`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "provider": "mock",
    "stage": "stt",
    "model": "<model>",
    "units": [
      {
        "unit": "audio_minute",
        "unit_price_micros": 1
      }
    ],
    "source": {
      "url": "https://example.test/a",
      "read_at": "<read_at>"
    },
    "source_figure": "<source_figure>",
    "verified": false
  }),
});
console.log(response.status, await response.text());

import os
import uuid

import requests

response = requests.post(
    f"{os.environ['VOCAL_API']}/v1/platform/vendor-prices",
    headers={
        "Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "provider": "mock",
        "stage": "stt",
        "model": "<model>",
        "units": [
            {
                "unit": "audio_minute",
                "unit_price_micros": 1,
            },
        ],
        "source": {
            "url": "https://example.test/a",
            "read_at": "<read_at>",
        },
        "source_figure": "<source_figure>",
        "verified": False,
    },
)
print(response.status_code, response.text)

Parameters

Name	In	Type	Required	Description
`idempotency-key`	header	string	no	A client-chosen key, kept 24 hours per Organization, environment and route. A replay returns the stored response.

Request body

Content type application/json, required: VendorPriceAddRequest.

Field	Type	Required	Description
`effective_from`	RequestTimestamp	no	The instant, in UTC, from which the entry is in force; the transaction's instant when absent. A later instant enters an upcoming price, which takes effect then with no deploy; an earlier one is refused with `price_effective_in_past`.
`model`	string or null	yes	The model priced, required on `stt`, `llm` and `tts`: a recognizer model, a language model, or the model a voice is spoken with. Null only on `telephony`, for a carrier minute, and on `platform`.
`note`	string	no	A conversion or a remark; never a secret or content.
`plan`	string	no	The vendor's plan or tier; none when absent.
`provider`	CostProvider	yes
`region`	string	no	The region the price applies to, as the vendor names it; none when absent.
`source`	VendorPriceSourceInput	yes
`source_figure`	string	yes	The figure as the source states it, such as a price per million tokens.
`stage`	CostStage	yes
`units`	array of VendorPriceUnitInput	yes	One or two units of the stage, each once: `audio_minute` on `stt`, `token_in` and `token_out` on `llm`, `character` on `tts`, `minute` on `telephony`, `minute` or `call` on `platform`.
`verified`	boolean	yes	True only when the price was read from `source` on its `read_at`.

Responses

Status	Content type	Shape	Error codes
`201`	`application/json`	VendorPriceAddResult
`400`	`application/json`	ErrorEnvelope	`invalid_request`
`401`	`application/json`	ErrorEnvelope	`unauthenticated`
`403`	`application/json`	ErrorEnvelope	`forbidden`
`409`	`application/json`	ErrorEnvelope	`idempotency_in_progress`, `idempotency_key_reused`
`422`	`application/json`	ErrorEnvelope	`validation_failed`
`429`	`application/json`	ErrorEnvelope	`rate_limited`
`500`	`application/json`	ErrorEnvelope	`internal_error`

Fields of the `201` answer

The shape is VendorPriceAddResult.

Field	Type	Required	Description
`object`	`"vendor_price_add"`	yes
`prices`	array of VendorPrice	yes	The rows written, one per unit of the request, in its order.
`replaced`	array of VendorPriceId	yes	The upcoming rows the entry replaced, by id; empty when it replaced none.