Models

In the eCourtDate Chatbot API, the OpenAI model field names a bot: a configured assistant with a persona, a slice of your knowledge base, and retrieval settings, set up for your account by eCourtDate. The models endpoints list the bots you can use so that OpenAI SDKs and model pickers work as they expect.

GET /v1/models
GET /v1/models/{modelId}
Scope: chat

Bots, slugs, and aliases

Each bot has a slug (court-assistant, jury-helpdesk), which is the value you pass as model. Your account can also have aliases: extra names that resolve to a bot, useful when an existing integration hard-codes a model name you cannot change. Aliases appear in the model list alongside slugs and are accepted everywhere a slug is.

Whatever name you send, responses from chat completions and conversations report the bot's canonical slug.

List models

curl -s "https://api.chatbots.ecourtdate.com/v1/models" \
  -H "Authorization: Bearer $API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "court-assistant",
      "object": "model",
      "created": 1779312019,
      "owned_by": "county-circuit-court"
    },
    {
      "id": "jury-helpdesk",
      "object": "model",
      "created": 1781990400,
      "owned_by": "county-circuit-court"
    },
    {
      "id": "gpt-4o",
      "object": "model",
      "created": 1779312019,
      "owned_by": "county-circuit-court"
    },
    {
      "id": "default",
      "object": "model",
      "created": 1779312019,
      "owned_by": "county-circuit-court"
    }
  ]
}

Field	Type	Description
`object`	string	Always `list`.
`data[].id`	string	A bot slug, an alias, or `default`. This is the value to send as `model`.
`data[].object`	string	Always `model`.
`data[].created`	integer	Unix time in seconds (UTC) when the bot was created. For an alias, its target bot's; for the `default` entry, the default bot's (the account's creation time for the built-in assistant).
`data[].owned_by`	string	Your account id.

The list contains every enabled bot, then every alias whose target bot is enabled, then default whenever the account default resolves (a configured default bot, a single enabled bot, or no enabled bots; see below). Disabled bots, and aliases that point to a disabled or missing bot, are not listed. When two or more bots are enabled and no default bot is configured, there is no default entry. The list is complete (no pagination) and query parameters are ignored.

If your account has no enabled bots, the list contains a single entry with id: "default", the built-in assistant described below.

With the OpenAI SDKs:

for model in client.models.list():
    print(model.id)

const models = await client.models.list();
for (const model of models.data) console.log(model.id);

Retrieve a model

GET /v1/models/{modelId} accepts a slug, an alias, or default. Lookups are case-sensitive and scoped to your account.

curl -s "https://api.chatbots.ecourtdate.com/v1/models/court-assistant" \
  -H "Authorization: Bearer $API_KEY"

{
  "id": "court-assistant",
  "object": "model",
  "created": 1779312019,
  "owned_by": "county-circuit-court"
}

Retrieving an alias returns the alias entry as it appears in the list (id is the alias, created is the target bot's). Retrieving default returns the default entry of the list; when the list has none (several enabled bots and no configured default), GET /v1/models/default is 404 model_not_found like any other unlisted name.

model = client.models.retrieve("court-assistant")
print(model.id, model.created)

The default model

Omitting model, sending null or "", or sending the literal "default" selects your account's default, resolved in this order:

The default bot configured for your account, if it is set and enabled.
Otherwise, the only enabled bot, if exactly one exists.
Otherwise, if no bot is enabled, a built-in assistant with slug default. It has no knowledge base, so it answers from general knowledge and its citations field is always null.

If two or more bots are enabled and no default bot is configured, a request without model (or with "default") is rejected, on chat completions and on conversation create alike:

{
  "error": {
    "message": "Multiple models are available for this account; pass 'model' explicitly, or ask eCourtDate to set a default model for your account.",
    "type": "invalid_request_error",
    "param": "model",
    "code": null
  }
}

Ask eCourtDate to set a default bot for your account if you want to omit model in production; otherwise always pass a slug.

model_not_found

A model that is not an enabled bot slug or alias in your account returns 404 model_not_found with param: "model". The message ends with a hint listing the slugs you can use (or stating that no models are configured). The same response is returned for a disabled bot, an alias to a disabled bot, a slug from another account, and a name that never existed, so it never reveals what exists elsewhere.

{
  "error": {
    "message": "Model 'traffic-bot' was not found. Available models: court-assistant, jury-helpdesk. Omit the 'model' field to use this account's default.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

The hint lists enabled slugs only (not aliases), sorted alphabetically, and closes with Omit the 'model' field to use this account's default. when a default resolves, or with Pass one of them. when several bots are enabled and no default is configured. It is for humans: branch on code and param, not on the message text. The same body, with the same message, is returned by chat completions, GET /v1/models/{modelId}, and conversation create. The OpenAI SDKs raise NotFoundError for this response.

How bots are configured

Bots are created and changed by eCourtDate for your account; there is no self-serve bot editor in the API. Changes take effect immediately. Each bot carries:

Setting	What it controls
Slug and aliases	The `model` names that select the bot. A slug is never `default` (that name is reserved for the account default), and no slug and alias on the account share a name.
Persona	Name, instructions, tone, and style. Your `system` and `developer` messages are appended after it (Chat completions).
Namespace	Which part of your knowledge base the bot retrieves from. Files and crawled pages are assigned to a namespace when ingested. A bot without a namespace does not retrieve and never cites.
Document filters	An optional fixed set of document ids within the namespace that the bot may cite.
Retrieval settings	How many passages are retrieved and handed to the model per request.
Citations	Whether text answers carry a `citations` array (`include_citations`, enabled by default); when it is off, `citations` is `null`. See Citations.
Generation settings	The token limit used when a request does not set its own, and the only limit used by conversations. Bots carry no sampling defaults: `temperature` and `top_p` are per request on chat completions, and an omitted value is left to the underlying language model.
Allowed tools	Which function names a request may offer, if any. See Per-bot tool allowlists.
Enabled	A disabled bot disappears from the list and returns `model_not_found` everywhere, including on conversations already bound to it.

A common setup is one bot per audience: a public court-assistant grounded in published notices and FAQs with no tools, and a staff clerk-tools bot with calendar and case-lookup functions, each on its own namespace.

Errors

Status	`code`	When
`401`	`invalid_api_key`	Missing or invalid key.
`403`	`insufficient_scope`	The key lacks the `chat` scope.
`404`	`model_not_found`	`GET /v1/models/{modelId}` for a name that is not in the list, including `default` when the account default is ambiguous; `param: "model"`.
`429`	`rate_limit_exceeded`, `insufficient_quota`	Both endpoints count toward the per-minute request limit, and a reached daily token quota blocks them too. Honor `Retry-After`.

All errors use the envelope described in Errors.

Bots, slugs, and aliases​

List models​

Retrieve a model​

The default model​

model_not_found​

How bots are configured​

Errors​