Aura Historia Operations API
Public process liveness and service readiness probes.
Public process liveness and service readiness probes.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/aura-historia-com:aura-historia-com-operations-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Aura Historia API Reference Operations API
description: '## Overview
The Aura Historia API powers the Aura Historia antiques platform and its partner-facing integrations. It exposes product discovery, listing source discovery, personalization, partner onboarding, and integration
workflows on top of Aura Historia''s serverless AWS platform. This reference is designed for two audiences:
- **Internal developers** building Aura Historia product-listings, operational tooling, and backoffice workflows
- **External partners and integrators** synchronizing inventory, consuming platform data, or
integrating with delegated access
## Core API domains
- **ProductListings and listing-sources** — search, retrieve, and explore product-listings, related product-listings, product
history, and listing source data
- **Personalization** — manage watchlists, saved search filters, and user notifications
- **Partner workflows** — submit partnership applications, maintain partnerships, ingest catalog data
in batches, and receive WooCommerce webhooks
- **Identity and access** — manage user accounts, Aura Historia access tokens, and OAuth 2.0
clients and token flows
- **Billing** — create Stripe checkout, billing-portal, and subscription-management sessions
## Authentication model
The API uses more than one authentication scheme depending on the route:
- **`BearerAuth`** — Cognito **access** JWT bearer tokens for authenticated user, admin, and
partner-user workflows. Cognito ID tokens are not accepted as API credentials. - **`AccessTokenAuth`** — Aura Historia opaque bearer access tokens created via
`/v1/me/access-tokens` or OAuth 2.0, primarily intended for partner automations and server-to-server
ingestion scenarios. When a route lists multiple security schemes, any one of the listed schemes may be accepted. Some read endpoints can also be called without authentication, while a valid user token may enrich
the response with personalized state such as watchlist, notification, or search-filter metadata. Aura Historia access
tokens receive only the sections their read scopes permit; see `ProductListingUserStateData`. ## MCP interface
The separate `https://mcp.aura-historia.com/v1` Streamable HTTP endpoint accepts opaque Aura access tokens only. Public calls may omit credentials; invalid supplied credentials receive HTTP 401, protected operations require their declared scopes, and insufficient grants receive HTTP 403 with the complete required scope set. Credential-free protected-resource metadata is served on the MCP host at `/.well-known/oauth-protected-resource` and `/.well-known/oauth-protected-resource/v1`. See the MCP contract for protocol and discovery details. ## Data and response conventions
- **PATCH:** an omitted request member remains unchanged. A documented nullable PATCH member
accepts `null` to clear its value; `null` for any other member returns `400 BAD_BODY_VALUE`. Use `[]`, not `null`, to replace a non-null collection with an empty collection. Empty HTTP
bodies are invalid, `{}` is a valid object-PATCH no-op, and the partner-product PATCH `[]`
remains a valid empty batch. Responses may omit absent optional values. - Product detail, watchlist, and saved-search match reads accept optional **`language`** and
**`currency`** parameters. Currency defaults to `EUR`. Detail pricing contains the seller''s source
amounts, converted display amounts, and FX valuation metadata. Active product-listings use the latest persisted
snapshot; sold product-listings use their immutable sale snapshot. Product history preserves immutable source values and accepts optional `currency` for historical FX display projections. History text is not localized. - Request-wide REST errors are returned as **`application/problem+json`** using a consistent RFC 9457-style structure
with `status`, `title`, `error`, optional `source`, and optional `detail`.'
version: 1.0.0
contact:
name: Aura-Historia Team
url: https://aura-historia.com/
license:
name: License
url: https://github.com/aura-historia/backend/blob/develop/LICENSE
servers:
- url: https://api.stage.aura-historia.com
description: Development environment
- url: https://api.aura-historia.com
description: Production environment
tags:
- name: Operations
description: Public process liveness and service readiness probes.
paths:
/v1/health:
get:
summary: Check process liveness
description: Returns the fixed `ok` response without checking dependencies.
operationId: getHealth
tags:
- Operations
security: []
responses:
'200':
description: The process is alive.
content:
text/plain:
schema:
type: string
example: 'ok
'
/v1/ready:
get:
summary: Check service readiness
description: Returns no diagnostic body when readiness fails.
operationId: getReadiness
tags:
- Operations
security: []
responses:
'204':
description: The readiness check succeeded.
'503':
description: The readiness check failed or timed out; no diagnostic body is returned.
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: 'Cognito access JWT bearer token. Signature, issuer, client, token use and expiry
are validated locally. Signed integer `auth_time` and `iat` claims are required;
sessions authenticated at or before the persisted local revocation cutoff are rejected.
This check shares the existing identity lookup and makes no live Cognito status request.
Revocation requested only in Cognito is not observed immediately; already-issued JWTs
can remain accepted until expiry. Use the administrator session-revocation endpoint
for immediate local enforcement. Database authentication failures return
`503 AUTH_TEMPORARILY_UNAVAILABLE`.
This scheme is used for authenticated user routes and for partner routes that accept Cognito user tokens.
'
AccessTokenAuth:
type: http
scheme: bearer
bearerFormat: opaque
description: 'Aura Historia bearer access token created through `/v1/me/access-tokens`.
Tokens are sent as standard bearer authorization headers.
Selected partner routes accept this scheme instead of the removed partner API-key flow.
'
x-tagGroups:
- name: Operations
tags:
- Operations
- name: Discovery
tags:
- ProductListings
- ListingSources
- Auctions
- name: User Experience
tags:
- Search Filters
- Watchlist
- Notifications
- User Account
- Billing
- Newsletter
- name: Partner & Platform Integrations
tags:
- Partnerships
- PartnershipApplications
- OAuth