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/dw2qC5qRwxuZ
  • GET 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 data exactly 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 _sys and data objects.


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_ready only.

  • Name
    content_flags
    Type
    object
    Description

    Flags keyed by page number (as a string). See Content flags. agent_ready only.

  • Name
    file
    Type
    object
    Description

    Kind, page count, MIME type, size, image metadata, name, processing, trust (verdict, reasons, pipeline_version, scanned_at) and, on agent_ready records, tainted_paths. It never contains links to page images or originals.

  • Name
    trust
    Type
    object
    Description

    The trust metadata below. A customer field named trust is 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

    clean or suspicious. Reported as suspicious when it cannot be read.

  • Name
    reasons
    Type
    string[]
    Description

    Finding kinds behind the verdict, such as hidden_text or policy_rule:<rule id>. See Finding kinds.

  • Name
    processing
    Type
    string
    Description

    agent_ready or storage_only. Reported as storage_only when 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).

ReasonTrust listMeaning
low_legibilityredactedBelow the legibility floor. Withheld and painted over.
unread_text_regionredactedA text-like region OCR did not read. Painted over.
hidden_native_textredactedSource text the rendering does not draw. Withheld.
unsupported_scriptunreliableReplaced by text not recognised: unsupported script.
low_confidenceunreliableDelivered; OCR was unsure.
low_resolutionunreliableDelivered; 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:

ProcessingFile-derived paths
agent_readyfile.original_filename, content
storage_onlyfile.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

Statuserror_codeWhen returned
401authentication_requiredMissing/invalid credentials or Secure timestamp outside ±15 minutes.
403access_deniedKey is authenticated but lacks access to this API prefix or collection.
404resource_not_foundResource key does not exist, is unpublished, or fails strict-reference validation.
404route_not_foundCollection path is not connected to the Flux API.
405action_not_allowedCollection is not configured for get_one in the API configuration (e.g., only search is allowed).
413max_response_size_exceededPopulated document exceeds the response size cap.
422validation_errorInvalid query parameters (e.g., malformed populate).

Was this page helpful?