# Convelio

> Convelio is a tech-enabled fine art logistics company (Paris / London) that ships high-value, fragile and oversized objects — paintings, sculpture, antiques and design — for galleries, auction houses, art fairs, dealers, collectors and online marketplaces. Its Shipping API returns an all-inclusive door-to-door price (packing, crating, customs, road/air/sea freight, insurance, white-glove delivery) instantly, in place of the multi-day manual quoting the art-handling trade traditionally runs on. Convelio publishes no llms.txt of its own; this file was generated by API Evangelist from Convelio's own public OpenAPI 3.1 document and developer portal.

## APIs

- [Convelio Shipping API v2.0](https://developers.convelio.com/): REST API for instant fine art shipping estimation, quoting, order booking and webhook subscriptions. Production base URL `https://api.convelio.com/v2`, sandbox `https://api.sandbox.convelio.com/v2`.

## Specs

- [OpenAPI 3.1.0 — Convelio Shipping API](https://raw.githubusercontent.com/api-evangelist/convelio/refs/heads/main/openapi/convelio-shipping-openapi.yml): 6 paths, 9 operations, 43 component schemas, 5 declared webhooks. Harvested from the server-rendered Redoc payload at developers.convelio.com; Convelio serves no standalone /openapi.json.
- [OpenAPI enhancements overlay](https://raw.githubusercontent.com/api-evangelist/convelio/refs/heads/main/overlays/convelio-shipping-overlay.yaml)

## Operations

- `estimateShippingPrice` — POST /shipping/estimate/price — first price estimation for a shipment, no record created.
- `createShippingQuote` — POST /shipping/quote — request a quote. Returns status `created` with an instant price, or `processing` when Convelio cannot price instantly (geography, oversized item, high commercial value) and its operations team produces a custom quote within 24h.
- `getShippingQuote` — GET /shipping/quote/{quoteId} — retrieve a quote and its status.
- `createShippingOrder` — POST /shipping/order — book a shipment from an existing `quote_id`, with billing details.
- `listWebhooks` — GET /webhook
- `createWebhook` — POST /webhook
- `getWebhook` — GET /webhook/{webhookId}
- `updateWebhook` — PUT /webhook/{webhookId}
- `deleteWebhook` — DELETE /webhook/{webhookId}

## Events

Declared in the OpenAPI 3.1 `webhooks` block, delivered as HTTP POST and signed with an HMAC-SHA256 `X-Convelio-signature` header. Subscribers answer `204`.

- `custom_quote_ready` — a price is available for a custom quote (payload: `quote_id`).
- `quote_paid` — a quote was paid (payload: `quote_id`, `tracking_link`).
- `order_created` — an order was created through the API (payload: `quote_id`, `order_id`).
- `shipment_status_changed` — a new shipment status was published (payload: `order_id`, `status`).
- `document_ready` — a new document is available (payload: `order_id`, `document_type`, `dashboard_order_link`).

## Authentication

- Single secret API key in the `Authorization` header, in the literal form `token <secret_key>`.
- The key prefix selects the environment: `sk_test_` works only against the sandbox server, `sk_live_` only against production.
- No OAuth, no OpenID Connect, no scopes — one key grants the full API surface.
- Keys are not self-service. Convelio issues them on request to **api@convelio.com**.

## Conventions

- Errors use an RFC 7807 problem-details body shape (`type`/`title`/`status`/`detail`), served as `application/json`. `422` adds a `validation_messages` map keyed by field name.
- Amounts are positive integers in the smallest currency unit. Currencies: EUR, USD, GBP.
- Country codes are ISO 3166-1 alpha-2. Item dimensions honour a per-request `measurement_system`.
- Versioning is doubled: a `/v2` URI prefix and a `application/vnd.convelio-shipping.v2+json` vendor media type.
- **No idempotency contract.** `createShippingQuote` and `createShippingOrder` are non-idempotent POSTs that create billable records; a naive retry can duplicate a quote or double-book a shipment.
- No pagination, no filtering, no field expansion, no request-id tracing, and no documented rate limits.

## Docs

- [Developer portal / API reference](https://developers.convelio.com/)
- [API key section](https://developers.convelio.com/#section/API-key)
- [API status page](https://developers.convelio.com/status)
- [Help centre](https://help.convelio.com/en)
- [API & Widget product overview](https://www.convelio.com/en/convelio-api/)
- [Platform overview](https://www.convelio.com/en/platform/)

## Artifacts

- [Authentication profile](https://raw.githubusercontent.com/api-evangelist/convelio/refs/heads/main/authentication/convelio-authentication.yml)
- [API conventions](https://raw.githubusercontent.com/api-evangelist/convelio/refs/heads/main/conventions/convelio-conventions.yml)
- [Error / problem types](https://raw.githubusercontent.com/api-evangelist/convelio/refs/heads/main/errors/convelio-problem-types.yml)
- [Webhook event catalogue](https://raw.githubusercontent.com/api-evangelist/convelio/refs/heads/main/asyncapi/convelio-webhooks.yml)
- [Data model](https://raw.githubusercontent.com/api-evangelist/convelio/refs/heads/main/data-model/convelio-data-model.yml)
- [Sandbox / test environment](https://raw.githubusercontent.com/api-evangelist/convelio/refs/heads/main/sandbox/convelio-sandbox.yml)
- [Lifecycle and versioning](https://raw.githubusercontent.com/api-evangelist/convelio/refs/heads/main/lifecycle/convelio-lifecycle.yml)
- [Conformance](https://raw.githubusercontent.com/api-evangelist/convelio/refs/heads/main/conformance/convelio-conformance.yml)
- [Domain security probe](https://raw.githubusercontent.com/api-evangelist/convelio/refs/heads/main/security/convelio-domain-security.yml)
- [Agent skills](https://raw.githubusercontent.com/api-evangelist/convelio/refs/heads/main/skills/_index.yml)

## Not published

Convelio serves no `/.well-known/` documents on any host — no `security.txt`, no `api-catalog`, no OpenID/OAuth metadata, no A2A agent card. It publishes no client SDKs (the public GitHub org has zero repositories), no CLI, no MCP server, no AsyncAPI document, no changelog, no deprecation policy, no SLA, and no trust centre or security certifications.