Hermes API

Listings

Run listings, resume runs with overrides, or publish drafts.

Functions

create_listingPOST /listings

curl -sS -X POST "https://api.hermes-api.dev/listings" \
  -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"
}'

Run the images → eBay listing pipeline.

create_listing_continuePOST /listings/continue

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

Resume the pipeline with client-provided overrides.

publish_listing_draftPOST /listings/publish-draft

curl -sS -X POST "https://api.hermes-api.dev/listings/publish-draft" \
  -H "X-Hermes-Key: $HERMES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "fulfillment_policy_id": "string",
  "listing": {
    "category_id": "string",
    "condition": "string",
    "condition_id": 0,
    "currency": "string",
    "description": "string",
    "images": [
      "string"
    ],
    "price": 0,
    "title": "string"
  },
  "merchant_location_key": "string",
  "payment_policy_id": "string",
  "return_policy_id": "string",
  "sku": "string"
}'

Publish a previously generated listing draft without re-running LLM stages.

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;
};

ContinueRequest

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

ImagesSource

export type ImagesSource = string | Array<string>;

ListingDimensionsInput

export type ListingDimensionsInput = {
  height: number;
  length: number;
  unit: string;
  width: number;
};

ListingDraftInput

export type ListingDraftInput = {
  aspects?: {
    [key: string]: Array<string>;
  };
  category_id: string;
  category_label?: string | null;
  condition: string;
  condition_id: number;
  currency: string;
  description: string;
  images: Array<string>;
  package?: null | ListingPackageInput;
  price: number;
  quantity?: number | null;
  title: string;
};

ListingDraftRequest — Publish a saved listing draft without re-running LLM stages.

export type ListingDraftRequest = {
  dry_run?: boolean;
  fulfillment_policy_id: string;
  listing: ListingDraftInput;
  marketplace?: MarketplaceId;
  merchant_location_key: string;
  payment_policy_id: string;
  publish?: boolean;
  return_policy_id: string;
  sku: string;
};

ListingPackageInput

export type ListingPackageInput = {
  dimensions?: null | ListingDimensionsInput;
  weight?: null | ListingWeightInput;
};

ListingResponse

export type ListingResponse = {
  listing_id: string;
  stages: Array<StageReport>;
};

ListingWeightInput

export type ListingWeightInput = {
  unit: string;
  value: number;
};

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";

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;
};

PublicStageOutput — Public-safe view of stage output to avoid leaking internal artifacts.

export type PublicStageOutput = {
  summary?: string | null;
  warnings?: Array<string> | null;
};

StageReport

export type StageReport = {
  elapsed_ms: number;
  name: string;
  output: PublicStageOutput;
  timestamp: string;
};