Browse documentation
API reference
Choose structured JSON for your application or Markdown content for an AI agent. Control the response with two headers.
On this page
Choose a format
JSON with original result fields is the default. Accept selects JSON or plain text; X-Respond-With: markdown converts the result content to Markdown. Your request body stays JSON.
| Response | Accept | X-Respond-With | Use for |
|---|---|---|---|
| JSON | application/json | Omit | Parsing fields in code · default |
| JSON + Markdown | application/json | markdown | Agent context with structured metadata |
| Plain text | text/plain | Omit | Reading original fields in a terminal |
| Text + Markdown | text/plain | markdown | Reading metadata and Markdown together |
Request and response examples
These tabs show the same Google Search in each format. Use Bash and cURL 7.76+ with FLASHDATA_API_KEY set to a key that allows google_search. Running a command submits one billable search.
Default. Parse the results array; the fields inside it depend on the source.
curl --fail-with-body --silent --show-error \
'https://data.flashdata.dev/v1/queries/realtime' \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{"source":"google_search","query":"vector databases"}'{
"source": "google_search",
"status": "done",
"results": [
{
"organic": [
{
"title": "Example page",
"link": "https://example.com/article",
"snippet": "A short source snippet."
}
]
}
],
"usage": {
"credits": 0.01
},
"created_at": "2026-10-22T12:00:00.000Z"
}Read content as a Markdown string. It replaces results; source, status and usage remain available as JSON fields.
curl --fail-with-body --silent --show-error \
'https://data.flashdata.dev/v1/queries/realtime' \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Respond-With: markdown' \
--data '{"source":"google_search","query":"vector databases"}'{
"source": "google_search",
"status": "done",
"usage": {
"credits": 0.01
},
"created_at": "2026-10-22T12:00:00.000Z",
"content": "# Google search\n\n## Organic\n\n### 1. Example page\n\n**Link:** <https://example.com/article>\n\n**Snippet:** A short source snippet\\.\n"
}Read the response as text. It contains the original fields in an indented layout, not a JSON document.
curl --fail-with-body --silent --show-error \
'https://data.flashdata.dev/v1/queries/realtime' \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--header 'Content-Type: application/json' \
--header 'Accept: text/plain' \
--data '{"source":"google_search","query":"vector databases"}'Source: "google_search"
Status: "done"
Results:
1:
Organic:
1:
Title: "Example page"
Link: "https://example.com/article"
Snippet: "A short source snippet."
Usage:
Credits: 0.01
Created at: "2026-10-22T12:00:00.000Z"
Read the response as text: metadata first, followed by Markdown content.
curl --fail-with-body --silent --show-error \
'https://data.flashdata.dev/v1/queries/realtime' \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--header 'Content-Type: application/json' \
--header 'Accept: text/plain' \
--header 'X-Respond-With: markdown' \
--data '{"source":"google_search","query":"vector databases"}'Source: "google_search"
Status: "done"
Usage: {"credits":0.01}
Created at: "2026-10-22T12:00:00.000Z"
Markdown Content:
# Google search
## Organic
### 1. Example page
**Link:** <https://example.com/article>
**Snippet:** A short source snippet\.
Supported endpoints
The same rules apply to Google Search and YouTube query sources. For YouTube Download, they format the delivery record, not the video or audio bytes. Account APIs, Bulk manifests and NDJSON parts, callbacks and MCP responses use their own formats.
| Endpoint | JSON / plain text | Markdown content |
|---|---|---|
| POST /v1/queries/realtime | Supported | Supported |
| GET /v2/jobs/{id}/results | Supported | Supported |
| POST /v1/queries | Submission receipt | Ignored — select it when reading results |
| POST /v1/queries/batch | Submission receipt | Ignored — select it when reading results |
| GET /v2/jobs/{id} | Job status | Ignored — no result content here |
Format a completed job result
Set the headers when reading the result, even if you set them at submission. Set JOB_ID to a completed job you can access. This GET reads existing results without submitting another query.
| Requested format | Result response |
|---|---|
| Original JSON | 302 with a signed storage URL in Location. Fetch that URL separately, without X-API-Key. Stored results may be gzip-compressed. |
| Plain text or either Markdown option | 200 with the formatted body directly in the response. |
curl --fail-with-body --silent --show-error \
"https://api.flashdata.dev/v2/jobs/${JOB_ID:?Set JOB_ID}/results" \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--header 'Accept: application/json' \
--header 'X-Respond-With: markdown'Format errors
API errors remain JSON or application/problem+json, even when you request plain text. Check the HTTP status before parsing the success format.
| Status / code | Fix |
|---|---|
| 400 · unsupported_representation | Use X-Respond-With: markdown or omit the header. Values such as json or text are not supported. |
| 406 · not_acceptable | Use Accept: application/json or text/plain. text/markdown and application/xml are not supported. |
Accept header details
Omit Accept or send */* to get JSON. Responses use UTF-8. Media ranges and q weights are supported; an unsupported charset returns 406 unless another acceptable range matches. Content-Type: application/json describes the request body, not the response.
Accept: text/plain; charset=utf-8, application/json;q=0.8