API Reference

Reports

File a bug report on the Hillwinds API.

When to file a report

Use this endpoint when you hit an unexpected 500, an obviously stale record, a filter that behaves differently than documented, or a documented endpoint that returns the wrong shape. Reports route directly to the API team and feed the next iteration of /docs/for-ai-agents's known-pitfalls list. Agents are encouraged to file reports — they help us catch problems that aren't yet known.

Create Report

POST/v1/reports0 credits

Parameter	Type	Description
`title`required	string	Short summary of the issue (one sentence).
`description`required	string	Full description: what was tried, what came back, what was expected.
`severity`	string	Optional free-text severity label. Common values are low, medium, high, and critical; the OpenAPI schema does not enforce an enum.
`endpoint`	string	Optional. The endpoint path that the report relates to (e.g., /companies).
`logs`	object	Optional. JSON object with diagnostic detail (request_id, response body excerpt, headers seen). Per spec it's typed object — the example below uses a string-valued field inside that object.

bash

curl -X POST -H "Authorization: Bearer ss_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Unexpected filter result for companies query",
    "description": "GET /v1/companies?signals=carrier_change&page_size=5 returned rows that did not include carrier_change in signals. Expected: only rows with a real carrier_change event.",
    "severity": "medium",
    "endpoint": "/companies",
    "logs": { "request_id": "ba74ff80f233c5e8a8325974a94a2821", "rows_returned": 5 }
  }' \
  "https://api.hillwinds.ai/v1/reports"

json

{
  "ok": true,
  "data": {
    "id": "edef7dcc-1d4e-442a-a86e-fe21ed54ddd3",
    "createdAt": "2026-06-10T02:41:52.463645",
    "endpoint": "/companies",
    "errorMessage": "Unexpected filter result for companies query: ...",
    "userId": null,
    "conversationId": null
  },
  "meta": { "credits_charged": 0 }
}

Response shape

The response combines title + description into errorMessage and stores severity / logs / metadata in stackTrace (JSON-encoded). This is internal storage shape; treat id as the only field you need to track. The API team will follow up via the email on your account.

PreviousCredits Next Errors Reference

Need a key?

Keys are issued by our team, not a signup form. Book a 25-minute walkthrough and you'll leave with sandbox and live credentials.

Get access Explore the platform