Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API 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.
openapi: 3.2.0
info:
title: Oddly Platform Data API
version: 1.0.0
description: 'Programmatic access to oddly''s deterministic commerce primitives for agents, automations, and partner tools. Authenticate with a bearer key minted at /dashboard/developers. Receipts are the rail: every response is traceable to the exact rule that produced it, so an answer is auditable, cacheable, and reproducible. All v1 endpoints are deterministic: same inputs, same outputs, no model in the hot path.'
servers:
- url: https://myoddly.com
security:
- bearerAuth: []
tags:
- name: Data
description: 'The metered corpus: citable benchmark claims, billed per answer served.'
paths:
/api/v1/data/claims:
get:
operationId: listDataClaims
tags:
- Data
summary: Query the corpus for citable benchmark claims
description: 'The metered DATA API. Returns the same privacy-floored figures the public /benchmarks pages publish, each with the anchor a citation quotes and the sha256 a consumer re-checks. Scope-gated on data:read rather than tier-gated: a data consumer is not a merchant. Metered per claim served (meter data.benchmark_query, unit citable_claim); the receipt hash and the units billed come back on x-oddly-usage-receipt and x-oddly-usage-units.'
parameters:
- name: category
in: query
required: false
description: Published category slug, e.g. baby-clothing. Omit for every published category.
schema:
type: string
- name: predicate
in: query
required: false
description: Exact claim predicate, the claim anchor without its claim- prefix, e.g. price-median or au-price-median.
schema:
type: string
- name: market
in: query
required: false
description: Two-letter market code, e.g. au. Returns only market-scoped claims.
schema:
type: string
- name: cursor
in: query
required: false
description: Opaque pagination cursor from a previous response's meta.next_cursor.
schema:
type: string
- name: limit
in: query
required: false
description: Page size. Default 25, max 100.
schema:
type: integer
minimum: 1
maximum: 100
default: 25
responses:
'200':
description: Sealed citable claims, with the corpus behind them and the verification procedure.
content:
application/json:
schema:
$ref: '#/components/schemas/Envelope'
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Authentication failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Key does not carry the data:read scope.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No published category with that slug.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- type
- code
- message
- request_id
properties:
type:
type: string
enum:
- invalid_request
- auth_invalid
- tier_required
- not_found
- rate_limited
- server_error
code:
type: string
message:
type: string
details:
type: object
nullable: true
request_id:
type: string
Envelope:
type: object
required:
- data
- meta
properties:
data:
type: object
description: The resource payload. Shape depends on the endpoint.
meta:
$ref: '#/components/schemas/Meta'
Meta:
type: object
required:
- request_id
- api_version
- tier
properties:
request_id:
type: string
description: Echoed in the X-Request-Id header. Quote it in support tickets.
api_version:
type: string
enum:
- v1
tier:
type: string
description: The caller's tier at request time.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: oddly_live_*
description: 'API key minted at /dashboard/developers. Send as: Authorization: Bearer oddly_live_...'