Get Resource
Method: GET /{api_prefix}/{collection_path}/{resource_key}
Auth: Flux API Key
Returns a single resource from a collection mapped to your Flux API. Use this endpoint when you know the exact collection path and resource key.
URL Pattern
GET https://{environment_key}.fxns.io/{api_prefix}/{collection_path}/{resource_key}
Examples:
GET https://7c9h4pwu.fxns.io/blog/articles/dw2qC5qRwxuZGET https://7c9h4pwu.fxns.io/commerce/catalog/items/9d2hX6qPZmL0
Flux resolves folder_path using the router configuration you publish in Management API. Ensure the collection is connected via Connect Collection to API before calling this endpoint.
Query Parameters
- Name
populate- Type
- string
- Description
Comma-separated list of reference fields to populate (
author,category.parent). Maximum depth is three levels.
- Name
return_locales- Type
- string
- Description
Comma-separated locales to include. Defaults to every locale enabled in the environment.
- Name
fallback_locales- Type
- boolean
- Default
- default:false
- Description
When
true, applies the environment’s fallback locale chain if a field is missing the requested translation.
- Name
raw- Type
- boolean
- Default
- default:false
- Description
Returns
dataexactly as stored (no locale processing or reference formatting). Use only when building low-level tooling.
Basic Retrieval
curl -X GET \
"https://7c9h4pwu.fxns.io/blog/articles/dw2qC5qRwxuZ" \
-H "Authorization: Secure <access_key>:<signature>"
Response
{
"_sys": {
"key": "dw2qC5qRwxuZ",
"revision": "8f2b1c9d",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z",
"folder": "aooxoscltikj"
},
"data": {
"title": "Introduction to AI",
"status": "published",
"author": "mK8pL2nRvXwQ"
}
}
Population
Populate replaces reference or relation IDs with the referenced documents (up to three levels deep).
GET https://7c9h4pwu.fxns.io/blog/articles/dw2qC5qRwxuZ?populate=author.company,category
Response with population
{
"_sys": {...},
"data": {
"title": "Introduction to AI",
"author": {
"_sys": {...},
"data": {
"name": "John Smith",
"company": {
"_sys": {...},
"data": { "name": "Tech Corp" }
}
}
},
"category": {
"_sys": {...},
"data": { "name": "Technology" }
}
}
}
Population follows the same rules as _search:
- Only reference or relation fields can be populated.
- Dot notation targets nested relationships (
author.company.location). - Responses obey the population depth limit.
Localization
Use return_locales to restrict which translations appear in the response, and fallback_locales=true to automatically plug gaps using environment fallback rules.
GET https://7c9h4pwu.fxns.io/blog/articles/dw2qC5qRwxuZ?return_locales=en,fr&fallback_locales=true
Localized response
{
"_sys": {...},
"data": {
"title": {
"en": "Introduction to AI",
"fr": "Introduction à l'IA"
},
"content": {
"en": "This comprehensive guide explores artificial intelligence...",
"fr": "Ce guide complet explore l'intelligence artificielle..."
}
}
}
Response Schema
Resource Object
- Name
_sys- Type
- object
- Description
System metadata about the resource.
- Name
data- Type
- object
- Description
Fields defined by the collection schema. Populated references contain nested
_sysanddataobjects.
Files Collections
A record of a files collection carries what came from the uploaded file next to its own fields. Everything file-derived is untrusted: the response marks it, and your code applies the marks to anything it forwards to a model. List and search responses carry the same blocks per record.
A record of a files collection
{
"data": {
"file": { "uuid": "9b1e5c3a-…", "original_filename": "invoice_march.pdf", "kind": "document",
"page_count": 2, "processing": "agent_ready",
"trust": { "verdict": "clean", "reasons": [] },
"tainted_paths": ["file.original_filename", "content"] },
"content": [{ "page": 1, "text": "# Invoice 2031 …" }, { "page": 2, "text": "…" }],
"content_flags": { "2": [{ "reason": "low_confidence", "scope": "line", "lines": [3, 4], "boxes": [[0.1, 0.5, 0.9, 0.6]] }] },
"trust": {
"version": 1, "source": "end_user_upload", "upload": "9b1e5c3a-…",
"verdict": "clean", "reasons": [], "processing": "agent_ready",
"redacted": [], "unreliable": [ { "page": 2, "reason": "low_confidence", "scope": "line", "lines": [3, 4], "boxes": [[0.1, 0.5, 0.9, 0.6]] } ],
"tainted_paths": ["file.original_filename", "content"]
}
}
}
- Name
content- Type
- object[]
- Description
The page-anchored markdown,
[{ page, text }].agent_readyonly.
- Name
content_flags- Type
- object
- Description
Flags keyed by page number (as a string). See Content flags.
agent_readyonly.
- Name
file- Type
- object
- Description
Kind, page count, MIME type, size, image metadata,
name,processing,trust(verdict,reasons,pipeline_version,scanned_at) and, onagent_readyrecords,tainted_paths. It never contains links to page images or originals.
- Name
trust- Type
- object
- Description
The trust metadata below. A customer field named
trustis overwritten.
- Name
moderation- Type
- object
- Description
Present while moderation is turned on:
{"status": "pending"}until the file's labels are stored, then the labels.
Trust object
- Name
version- Type
- integer
- Description
1.
- Name
source- Type
- string
- Description
end_user_upload. The set is open: treat an unknown value as untrusted.
- Name
upload- Type
- string
- Description
The upload identifier, equal to
file.uuid.
- Name
verdict- Type
- string
- Description
cleanorsuspicious. Reported assuspiciouswhen it cannot be read.
- Name
reasons- Type
- string[]
- Description
Finding kinds behind the verdict, such as
hidden_textorpolicy_rule:<rule id>. See Finding kinds.
- Name
processing- Type
- string
- Description
agent_readyorstorage_only. Reported asstorage_onlywhen it cannot be read.
- Name
redacted- Type
- object[]
- Description
Regions withheld from the text and painted over in the page images:
{ page, reason, boxes }. Always present.
- Name
unreliable- Type
- object[]
- Description
Delivered but flagged text:
{ page, reason, scope, lines, boxes }. Always present.
- Name
tainted_paths- Type
- string[]
- Description
See Tainted paths.
boxes are [x0, y0, x1, y1] as fractions of the page width and height.
Content flags
Each entry has reason, scope (line, page or region), lines (zero-based, empty unless line) and boxes (empty for a whole page).
| Reason | Trust list | Meaning |
|---|---|---|
low_legibility | redacted | Below the legibility floor. Withheld and painted over. |
unread_text_region | redacted | A text-like region OCR did not read. Painted over. |
hidden_native_text | redacted | Source text the rendering does not draw. Withheld. |
unsupported_script | unreliable | Replaced by text not recognised: unsupported script. |
low_confidence | unreliable | Delivered; OCR was unsure. |
low_resolution | unreliable | Delivered; page rendered below the minimum text height. |
Any other reason is reported under unreliable.
Tainted paths
tainted_paths lists the paths of the record that hold untrusted values. Treat every listed path as untrusted. The file-derived paths are:
| Processing | File-derived paths |
|---|---|
agent_ready | file.original_filename, content |
storage_only | file.original_filename, file.mime_type |
Fields of the record that guardrails mark as untrusted are listed too. file.name, set by your application, is not listed unless guardrails mark it.
Storage-only records
A storage_only record has no content, content_flags, page count, image metadata or links. Its file block holds uuid, mime_type, name, original_filename, size, trust and processing; tainted_paths is only in the trust object, which has "processing": "storage_only".
Errors
| Status | error_code | When returned |
|---|---|---|
| 401 | authentication_required | Missing/invalid credentials or Secure timestamp outside ±15 minutes. |
| 403 | access_denied | Key is authenticated but lacks access to this API prefix or collection. |
| 404 | resource_not_found | Resource key does not exist, is unpublished, or fails strict-reference validation. |
| 404 | route_not_found | Collection path is not connected to the Flux API. |
| 405 | action_not_allowed | Collection is not configured for get_one in the API configuration (e.g., only search is allowed). |
| 413 | max_response_size_exceeded | Populated document exceeds the response size cap. |
| 422 | validation_error | Invalid query parameters (e.g., malformed populate). |
Related Endpoints
- List Resources — GET many resources from a collection.
- Search — POST advanced filters, joins, and vector search.
- Management API Resources — Create or manage resource content.