Response formats — SpiderIQ

Most read endpoints in the SpiderIQ API can answer in four different formats. You pick one with a format query parameter. This page explains what each value does, when to reach for it, and what happens when you send something the endpoint cannot serve.

The four values

Value	You get back	Content type
`json`	the ordinary JSON body. This is the default when you send no `format` at all	`application/json`
`llm`	the same JSON body, plus a `guidance` block describing what the resource is for, what to call next, and the mistakes callers actually make	`application/json`
`yaml`	the same data serialised as YAML, which is meaningfully cheaper to read	`text/yaml`
`md`	a human-readable Markdown rendering	`text/markdown`

curl "https://spideriq.ai/api/v1/jobs/{job_id}/results?format=yaml" \
  -H "Authorization: Bearer $TOKEN"

Which one you want

If you are writing code, send nothing. The default is JSON and it is the format every client library expects.

If you are an AI agent, send format=llm. The guidance block is the reason it exists: alongside the data you get a short description of what this endpoint is for, what it is explicitly not for, and what to call next. That saves a round trip through the documentation on every call.

Bearer and PAT callers are opted into guidance by default, so you often do not need to send anything. Sending format=llm makes the intent explicit and is safe either way.

If you want to turn guidance off for one request, send format=json. An explicit format always beats the Bearer default.

If you are reading a response into a context window, try format=yaml. It carries the same fields with markedly less punctuation, which is worth 40 to 60 percent of the tokens on a large body. You can also set SPIDERIQ_FORMAT=yaml once in your MCP configuration instead of adding the parameter to every call.

What a rejected value looks like

An unsupported value is refused rather than quietly answered in JSON:

{
  "error": {
    "code": "SCHEMA_VALIDATION_FAILED",
    "errors": [{ "type": "enum", "loc": ["query", "format"] }]
  }
}

That refusal is deliberate. Accepting a format the endpoint cannot render, and answering in JSON anyway, would mean a Markdown request silently returning something that is not Markdown.

The endpoints that accept less than four

A small number of endpoints genuinely serve a narrower set, and they refuse the rest for the same reason:

Press releases and doc exports render Markdown but have no YAML renderer, so format=yaml returns a 422 there.
Lead export defaults to csv rather than JSON, because a spreadsheet is what callers of that endpoint want. It also accepts json and llm.
Page export adds archive, which returns a ZIP laid out the way the VSCode extension stores a site locally.

If you are unsure what a specific endpoint accepts, the API reference lists the permitted values for every one of them, and an invalid value is always a 422 rather than a surprise.