---
title: "List the models a provider offers"
method: POST
path: "/v1/configurations/discover-models"
tags: ["Configurations"]
---

# List the models a provider offers

`POST /v1/configurations/discover-models`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/configurations/discover-models`
- Auth: HTTP bearer

Fetch a provider's model listing and read it. The request names the provider, the
address of its listing and how the listing is shaped; ToolPiper fetches it with the
credential stored for that host and returns the models. A cloud host needs a plan
with cloud models. A local server needs no credential. ToolPiper's own address
returns its own listing.

## Request body

- object
  - `providerId` string, required: The provider's catalog id.
  - `protocol` 'http' | 'https', required
  - `host` string, required: Host name or address, without a scheme or path.
  - `port` string, required
  - `discovery` object, required
    - `endpoint` string, required: Path of the provider's model listing, for example `/v1/models`.
    - `responsePath` string, required: Dotted path to the array of models in the answer. Empty when the answer is the array.
    - `requiresAuth` boolean
    - `modelNameField` string: Field naming a model. `name`, `id` and `model` are read when it is absent.
    - `modelFilter` string: Regular expression. A model whose name matches is left out.
    - `kindInference` 'openai' | 'anthropic' | 'gemini' | 'entry': How a model's kind is told from its listing entry.
    - `contextWindowPath` string: Dotted path, in each entry, to the context window in tokens.
    - `maxOutputTokensPath` string: Dotted path, in each entry, to the output token limit.
  - `additionalHeaders` object: The provider's static headers. Never a credential.

## Response `200`

The provider's models, in the provider's order

- object
  - `models` object[], required
    - `name` string, required
    - `displayName` string, required
    - `kind` 'chat' | 'responses' | 'reasoning' | 'completion' | 'embedding' | 'image' | 'audio' | 'unknown'
    - `capabilities` object: Anthropic's capabilities object, as the provider wrote it.
    - `contextWindow` integer
    - `maxOutputTokens` integer

## Other responses

- `400`: Invalid request
- `402`: The plan does not include cloud models
- `502`: The provider could not be reached, answered with an error or sent a listing in another shape

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)