Hermes API

Billing & usage

Checkout sessions, portal access, top-ups, pricing quotes, and usage windows.

Functions

billing_checkout_sessionPOST /billing/checkout-session

curl -sS -X POST "https://api.hermes-api.dev/billing/checkout-session" \
  -H "X-Hermes-Key: $HERMES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

billing_portal_sessionPOST /billing/portal

curl -sS -X POST "https://api.hermes-api.dev/billing/portal" \
  -H "X-Hermes-Key: $HERMES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

billing_topupPOST /billing/top-ups

curl -sS -X POST "https://api.hermes-api.dev/billing/top-ups" \
  -H "X-Hermes-Key: $HERMES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "units": 0
}'

Create a Stripe Checkout session for credits top-ups.

pricing_quotePOST /v1/pricing/quote

curl -sS -X POST "https://api.hermes-api.dev/v1/pricing/quote" \
  -H "X-Hermes-Key: $HERMES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "fulfillment_policy_id": "string",
  "images_source": "string",
  "merchant_location_key": "string",
  "payment_policy_id": "string",
  "return_policy_id": "string"
}'

handle_get_usageGET /v1/usage

curl -sS "https://api.hermes-api.dev/v1/usage" \
  -H "X-Hermes-Key: $HERMES_API_KEY"

Types

Request and response shapes pulled directly from the OpenAPI schema.

ApiError

export type ApiError = {
  code?: string | null;
  detail?: string | null;
  error: string;
  fields?: {
    [key: string]: string;
  } | null;
  request_id?: string | null;
};

CategorySelectionInput

export type CategorySelectionInput = {
  confidence: number;
  id: string;
  label: string;
  rationale: string;
  tree_id: string;
};

CheckoutRequest

export type CheckoutRequest = {
  cancel_url?: string | null;
  price_id?: string | null;
  price_lookup_key?: string | null;
  quantity?: number;
  success_url?: string | null;
};

CheckoutResponse

export type CheckoutResponse = {
  url: string;
};

ImagesSource

export type ImagesSource = string | Array<string>;

LlmModel

export type LlmModel = "gpt-5.2" | "gpt-5-mini" | "gpt-5-nano";

LlmStageOptions

export type LlmStageOptions = {
  model: LlmModel;
  reasoning?: boolean;
  web_search?: boolean;
};

MarketplaceId

export type MarketplaceId = "EBAY_US" | "EBAY_UK" | "EBAY_DE";

PortalRequest

export type PortalRequest = {
  return_url?: string | null;
};

PortalResponse

export type PortalResponse = {
  url: string;
};

PricingQuote

export type PricingQuote = {
  breakdown: {
    [key: string]: number;
  };
  credits_applied_cents?: number;
  credits_estimated: number;
  enterprise?: boolean;
  net_due_cents?: number;
  tiers?: Array<TierLine>;
  unit_rate_cents?: number;
};

PublicListingRequest — Public-facing listing request without internal LLM override knobs.

export type PublicListingRequest = {
  dry_run?: boolean;
  fulfillment_policy_id: string;
  images_source: ImagesSource;
  llm_aspects?: null | LlmStageOptions;
  llm_ingest?: null | LlmStageOptions;
  marketplace?: MarketplaceId;
  merchant_location_key: string;
  overrides?: null | PublicPipelineOverrides;
  payment_policy_id: string;
  publish?: boolean;
  return_policy_id: string;
  sku?: string;
  use_signed_urls?: boolean;
};

PublicPipelineOverrides — Public-safe subset of pipeline overrides.

export type PublicPipelineOverrides = {
  category?: null | CategorySelectionInput;
  condition?: string | null;
  condition_id?: number | null;
  product?: unknown;
  resolved_images?: Array<string> | null;
};

TieredUsage

export type TieredUsage = {
  cost_cents: number;
  credit_balance_cents: number;
  credits_applied_cents: number;
  enterprise: boolean;
  net_due_cents: number;
  tiers: Array<TierLine>;
  total_events: number;
  total_units: number;
};

TierLine

export type TierLine = {
  cost_cents: number;
  enterprise?: boolean;
  from: number;
  rate_cents: number;
  to?: number | null;
  units: number;
};

TopUpRequest

export type TopUpRequest = {
  cancel_url?: string | null;
  success_url?: string | null;
  units: number;
};

TopUpResponse

export type TopUpResponse = {
  url: string;
};

UsageCounters

export type UsageCounters = {
  credits_consumed: number;
  jobs_enqueued: number;
  listings_run: number;
};

UsageSummary

export type UsageSummary = {
  counters: UsageCounters;
  org_id: string;
  tiered?: null | TieredUsage;
  window_from?: string | null;
  window_to?: string | null;
};