Contract snapshot 0.101.0 · Deployment and client release availability follow the integration note for your environment.
Create a quote
Send a request matching the current schema. Present its scope, credit ceiling and expiry to the user. Creating a quote is not a completed data delivery.
Approval is an explicit action
For work without a published rate, obtain approval before execution. Recurring work must show both per-delivery and monthly cost before the first delivery.
Reserve does not mean delivered
An approval reserves a ceiling. Read the returned quote and reservation state; do not treat the reservation as a delivery receipt or a settled charge. Do not automatically repeat an approval whose outcome is uncertain.
Review scope changes before approval
A useful quote review presents the question, sources, fields, period and delivery expectation together with its ceiling and expiry. If those requirements change, review the applicable quote again. Do not treat a previous approval as standing permission for a different dataset or a new recurring schedule.
Handle an uncertain approval
Disable duplicate submission while awaiting a response. If the connection fails, read the known quote state before offering another approval action. Show whether the outcome is confirmed or still unknown. Preserve the quote identifier for reconciliation without exposing authorisation credentials.
POST
/v1/quotes
Price a request
What to price: a catalogue recipe, how many units of its data are wanted, and the extras to use. Add a cadence for a recurring report or watch to see the cost of each delivery and of a month. The organisation is taken from the credential, never from the body.
Request body schema
{
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QuoteRequest"
}
}
}
}| Status | Meaning |
|---|---|
| 201 | Success |
| 400 | Error. The `error.code` is one of: - `invalid_request`: retry advice `fix_request` |
| 401 | Error. The `error.code` is one of: - `key_expired`: retry advice `refresh_credentials` - `key_revoked`: retry advice `refresh_credentials` - `session_expired`: retry advice `refresh_credentials` - `unauthenticated`: retry advice `refresh_credentials` |
| 403 | Error. The `error.code` is one of: - `org_missing`: retry advice `never` - `scope_missing`: retry advice `never` |
| 404 | Error. The `error.code` is one of: - `unknown_capability`: retry advice `fix_request` |
| 429 | Error. The `error.code` is one of: - `rate_limited`: retry advice `after_reset` |
| 500 | Error. The `error.code` is one of: - `internal`: retry advice `bounded` |
| 503 | Error. The `error.code` is one of: - `unavailable`: retry advice `bounded` |
Full response fields and reusable schemas are in the downloadable OpenAPI contract.
GET
/v1/quotes/{id}
Read a quote
A quote of your organisation: the priced lines, the ceiling, and when it expires. Another organisation's quote is not found.
Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"description": "The quote id."
}
}
]| Status | Meaning |
|---|---|
| 200 | Success |
| 400 | Error. The `error.code` is one of: - `invalid_request`: retry advice `fix_request` |
| 401 | Error. The `error.code` is one of: - `key_expired`: retry advice `refresh_credentials` - `key_revoked`: retry advice `refresh_credentials` - `session_expired`: retry advice `refresh_credentials` - `unauthenticated`: retry advice `refresh_credentials` |
| 403 | Error. The `error.code` is one of: - `org_missing`: retry advice `never` - `scope_missing`: retry advice `never` |
| 404 | Error. The `error.code` is one of: - `not_found`: retry advice `fix_request` |
| 429 | Error. The `error.code` is one of: - `rate_limited`: retry advice `after_reset` |
| 500 | Error. The `error.code` is one of: - `internal`: retry advice `bounded` |
| 503 | Error. The `error.code` is one of: - `unavailable`: retry advice `bounded` |
Full response fields and reusable schemas are in the downloadable OpenAPI contract.
POST
/v1/quotes/{id}/approve
Approve a quote
The quote after approval, and the credits held for the run: free credits first, then paid. Approving an expired or already approved quote, or one that is not yours, is refused.
Parameters
[
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"description": "The quote id."
}
}
]Request body schema
{
"required": false,
"content": {
"application/json": {
"schema": {
"title": "ApproveQuoteRequest",
"description": "Optional. confirmedCeiling: the credits the person approving was shown and agreed to. When sent, the approval is refused with cost_changed unless it is exactly the quote’s ceiling, so an assistant cannot approve a cost the person did not see.",
"type": "object",
"additionalProperties": false,
"properties": {
"confirmedCeiling": {
"type": "integer",
"minimum": 0
}
},
"examples": [
{
"confirmedCeiling": 12
}
]
}
}
}
}| Status | Meaning |
|---|---|
| 200 | Success |
| 400 | Error. The `error.code` is one of: - `invalid_request`: retry advice `fix_request` |
| 401 | Error. The `error.code` is one of: - `key_expired`: retry advice `refresh_credentials` - `key_revoked`: retry advice `refresh_credentials` - `session_expired`: retry advice `refresh_credentials` - `unauthenticated`: retry advice `refresh_credentials` |
| 402 | Error. The `error.code` is one of: - `credits_exhausted`: retry advice `never` - `plan_required`: retry advice `never` |
| 403 | Error. The `error.code` is one of: - `org_missing`: retry advice `never` - `scope_missing`: retry advice `never` |
| 404 | Error. The `error.code` is one of: - `not_found`: retry advice `fix_request` - `unknown_capability`: retry advice `fix_request` |
| 409 | Error. The `error.code` is one of: - `cost_changed`: retry advice `never` - `quote_already_approved`: retry advice `never` |
| 410 | Error. The `error.code` is one of: - `quote_expired`: retry advice `fix_request` |
| 429 | Error. The `error.code` is one of: - `rate_limited`: retry advice `after_reset` |
| 500 | Error. The `error.code` is one of: - `internal`: retry advice `bounded` |
| 503 | Error. The `error.code` is one of: - `unavailable`: retry advice `bounded` |
Full response fields and reusable schemas are in the downloadable OpenAPI contract.