---
title: "Agents & machine formats"
description: "Every page of this reference as Markdown, plain text, JSON and OpenAPI 3.1 — and how to point a coding agent at it."
canonical: "https://thecarapi.com/docs/agents"
contract_version: "2026-08-19"
api_base: "https://api.thecarapi.com"
source: "https://thecarapi.com/docs/agents.md"
---

# Agents & machine formats

Every page of this reference as Markdown, plain text, JSON and OpenAPI 3.1 — and how to point a coding agent at it.

This documentation is generated from structured data, so it can be served in whatever shape reads it. If you are integrating with a coding agent or an LLM, take one of the files below rather than parsing these HTML pages.

## Formats

| Format | URL | Use it for |
| --- | --- | --- |
| Markdown, one page | `https://thecarapi.com/docs/<section>.md` | Pasting a single section into a prompt or a repo. |
| Markdown, everything | `https://thecarapi.com/docs/thecarapi-api-reference.md` | The entire reference as one file, front matter included. |
| Plain text, everything | `https://thecarapi.com/docs/thecarapi-api-reference.txt` | Context windows and tools that choke on Markdown tables. |
| JSON | `https://thecarapi.com/docs/thecarapi-api-reference.json` | Programmatic access to sections, endpoints, parameters and response fields. |
| OpenAPI 3.1 | `https://thecarapi.com/openapi.json` | Client generation, Postman/Insomnia import, agent tool definitions. |
| Postman collection | `https://thecarapi.com/thecarapi.postman_collection.json` | Import straight into Postman — every endpoint, grouped and described. |
| `llms.txt` | `https://thecarapi.com/llms.txt` | The site index in the llms.txt convention. |
| Docs index for agents | `https://thecarapi.com/docs/llms.txt` | Just the documentation tree, with a one-line summary per section. |

Every docs page also advertises its Markdown twin in the head as `<link rel="alternate" type="text/markdown">`, and the **Copy** and **Download** controls at the top of each page produce exactly these files client-side.

## Fetching them

```bash
# One section
curl -sS https://thecarapi.com/docs/live-prices.md

# The whole reference, as Markdown
curl -sS https://thecarapi.com/docs/thecarapi-api-reference.md

# The endpoint surface, as OpenAPI 3.1
curl -sS https://thecarapi.com/openapi.json | jq '.paths | keys'
```

_These are static files. No API key is needed to read the documentation._

## Giving an agent the right context

The full reference is large. For most tasks an agent needs three things: the conventions, the data dictionary, and the one endpoint group it is calling. Fetching those three sections is cheaper and more accurate than dropping the whole document into a context window.

```text
You are integrating with TheCarApi.

Read these first:
  https://thecarapi.com/docs/conventions.md     — envelope, ETags, pagination, rate limits
  https://thecarapi.com/docs/errors.md          — status codes and what is worth retrying
  https://thecarapi.com/docs/<group>.md         — the endpoint group you are calling
  https://thecarapi.com/openapi.json            — machine-readable parameter and response shapes

Rules that are not obvious from the schema:
  - A vehicle is addressed by site_name + auction_id, e.g. encar/38112900.
  - Prices are JSON numbers, never strings.
  - An absent live_price block is normal, not an error.
  - Never hardcode the source list; read /api/sites and /api/contract at startup.
  - Retry 429/503 honouring Retry-After. Never retry 400/401/403/404.
```

_A starting prompt. Swap `<group>` for `search`, `auctions`, `car-details` and so on._

## Crawling policy

`robots.txt` allows search and AI citation crawlers and disallows bulk training harvesters. The documentation is public and unauthenticated; the API behind it is not. Nothing in these files is a credential, and no endpoint here will answer without a key.

> **Generated, not hand-maintained** — Every format on this page is emitted from the same source at build time, so they cannot drift from each other or from the HTML. If a section changes, all seven change with it.