Requests

/api/v1/requests — request vehicles and features, upvote, comment; tell us about you.

The catalog is large but not complete, and the API does not do everything yet. When a vehicle is missing or a feature would help, ask for it. Requests are public at /requests: anyone can read them, and anyone with a key, a connected agent or a dashboard login can request, upvote and comment. Votes decide what we build next, and the people involved hear back when it ships.

List requests

GET/api/v1/requests

nonefree

Query parameters
Parameter	Type	Description
`kind`	"vehicle" \| "feature"	Only one kind. Omit for both.
`status`	"open" \| "planned" \| "in_progress" \| "done" \| "declined"	Filter by status. Omit for everything except declined.
`sort`	"top" \| "new"	Most votes first (default) or newest first.
`limit`	integer 1–100	Page size; default 25.
`cursor`	string	`next_cursor` from the previous page.

Responses are public and cacheable for a minute. Send your key anyway and each record gains viewer.voted, telling you whether you already upvoted it. Authors appear by first name only; email addresses never leave the account.

bash

curl https://carimage.dev/api/v1/requests?kind=vehicle&sort=top

200 OK

{
  "data": [
    {
      "id": "3f0c2a7e-9b1d-4c6e-8a2b-0d7c5e3f1a2b",
      "kind": "vehicle",
      "title": "Rivian R1T (2024)",
      "body": null,
      "vehicle": {
        "make": "Rivian",
        "model": "R1T",
        "year": 2024
      },
      "status": "open",
      "votes": 1,
      "comments": 0,
      "author": "Jonathan",
      "url": "https://carimage.dev/requests/3f0c2a7e-9b1d-4c6e-8a2b-0d7c5e3f1a2b",
      "created_at": "2026-09-11T10:00:00Z",
      "updated_at": "2026-09-11T10:00:00Z",
      "viewer": {
        "voted": true
      }
    }
  ],
  "next_cursor": null,
  "request_id": "req_01ja0…"
}

GET /api/v1/requests/{id} returns one request with its full thread as comments (an array here, a count in the list) plus comment_count.

Request a vehicle or a feature

POST/api/v1/requests

account:readfree

Request body
Parameter	Type	Description
`kind`required	"vehicle" \| "feature"	What you are asking for.
`make`	string ≤ 80	Vehicle only, required. Case does not matter.
`model`	string ≤ 80	Vehicle only, required.
`year`	integer 1900–2035	Vehicle only, optional. Omit to ask for the model in general.
`title`	string ≤ 120	Feature only, required. Vehicle titles are generated (“Rivian R1T (2024)”).
`body`	string ≤ 2000	Details: the use case, body style, trim, anything that helps prioritise.

bash

curl -X POST https://carimage.dev/api/v1/requests \
  -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "vehicle", "make": "Rivian", "model": "R1T", "year": 2024}'

201 Created

{
  "data": {
    "id": "3f0c2a7e-9b1d-4c6e-8a2b-0d7c5e3f1a2b",
    "kind": "vehicle",
    "title": "Rivian R1T (2024)",
    "body": null,
    "vehicle": {
      "make": "Rivian",
      "model": "R1T",
      "year": 2024
    },
    "status": "open",
    "votes": 1,
    "comments": 0,
    "author": "Jonathan",
    "url": "https://carimage.dev/requests/3f0c2a7e-9b1d-4c6e-8a2b-0d7c5e3f1a2b",
    "created_at": "2026-09-11T10:00:00Z",
    "updated_at": "2026-09-11T10:00:00Z",
    "viewer": {
      "voted": true
    }
  },
  "deduplicated": false,
  "request_id": "req_01ja0…"
}

No duplicates, by design

A vehicle that already has an open request for the same make, model and year is not created twice: the existing request is upvoted and returned with 200 and deduplicated: true. Calling it is always safe. Feature requests are free text and are not deduplicated, so check the list and upvote a match first.

Your own vote counts, so a new request starts at one. A new request also earns you one short thank-you email with the link to its page; dedup hits, upvotes and comments never email anyone. When staff move a request to In progress and to Done, everyone who requested, upvoted or commented gets one note each.

Upvote and comment

POST/api/v1/requests/{id}/votes

account:readfree

DELETE/api/v1/requests/{id}/votes

account:readfree

POST/api/v1/requests/{id}/comments

account:readfree

Votes are idempotent: voting twice changes nothing, DELETE takes yours back. Both return the updated request. Comments take {"body": "…"} (1–1000 characters) and return 201 with the comment; GET on the same path lists the thread without a key.

bash

curl -X POST https://carimage.dev/api/v1/requests/3f0c2a7e-9b1d-4c6e-8a2b-0d7c5e3f1a2b/comments \
  -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body": "We need the 2022-2024 body style for a dealer site."}'

Tell us about you

POST/api/v1/account/building

account:readfree

POST/api/v1/account/referral

account:readfree

Two optional questions, also on the dashboard: what are you building ({"building": "…"}, up to 2000 characters) and how did you find us ({"source": "…", "detail"?: "…"}). Sources: search, ai_assistant, github, npm, twitter_x, linkedin, reddit, hacker_news, youtube, friend_or_colleague, blog_or_article, other.

These answers are private: they are stored on your account, overwritten when you answer again, and never returned by any public endpoint. The first answer to each earns a short thank-you. Agents should only send what the person actually said, with their consent.

From the CLI and MCP

car-image request list, request vehicle --make Rivian --model R1T --year 2024, request feature "Interior views", request show|upvote|comment <id>.
car-image about building "…" and car-image about referral github.
MCP tools list_requests, request_vehicle, request_feature, get_request, upvote_request, comment_on_request, share_building, share_referral. The server tells agents to offer request_vehicle when a catalog search finds nothing.

Errors

400 — missing make/model or title, a year out of range, a body too long, an unknown referral source.
404 — no request with that id.
429 — more than 20 requests or 60 comments in an hour from one account (Retry-After says when).