Schema Introspection

Method: GET /{api_prefix}/{collection_path}/_schema
Auth: Flux API Key

Returns the current JSON Schema and metadata for a connected Flux resource path, including searchable vs non-searchable fields. Use this endpoint to build typed clients, validation layers, or dynamic UIs from live schema data.

URL Pattern

GET https://{environment_key}.fxns.io/{api_prefix}/{collection_path}/_schema

Examples:

GET https://7c9h4pwu.fxns.io/blog/articles/_schema
GET https://7c9h4pwu.fxns.io/blog/projects/{projects_id}/tasks/_schema

/_schema is valid only for collection routes. Calling /{resource_key}/_schema is not supported and returns route_not_found.

Response Object

Name
json_schema
Type
object
Description
JSON Schema document for the currently active schema version.
Name
json_schema.$defs
Type
object
Description
Embedded definitions block inside json_schema. Nested-Component fields are expressed as a local reference ({"$ref": "#/$defs/<component>"}), and every referenced Component schema is inlined here. Present only when the schema references at least one Component.
Name
searchable_fields
Type
array<string>
Description
Field paths that are indexed and available for filtering/search (where, find_text, find_phrase).
Name
non_searchable_fields
Type
array<string>
Description
Field paths present in schema but not indexed for filtering/search.
Name
path
Type
string
Description
Resource path without the /_schema suffix (includes API prefix).
Name
actions
Type
array<string>
Description
Enabled read actions for this resource path (get_many, get_one).
Name
alias
Type
string
Description
Collection alias (when available).
Name
content_type
Type
string
Description
Collection content type (document, collection, etc.) when available.
Name
schema_key
Type
string
Description
Schema key.
Name
schema_version_key
Type
string
Description
Active schema version key.

The returned schema is self-contained: every $ref resolves within the document itself (against the embedded $defs), so consumers never fetch external definitions. See Agent-Native Knowledge API for how this powers autonomous discovery.

Example

curl "https://7c9h4pwu.fxns.io/blog/articles/_schema" \
  -H "Authorization: Secure <access_key>:<signature>"

Response

{
  "json_schema": {
    "type": "object",
    "required": ["title"],
    "properties": {
      "title": {"type": "string", "maxLength": 255},
      "published_at": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T"},
      "author": {"$ref": "#/$defs/cmp_author"}
    },
    "additionalProperties": false,
    "$defs": {
      "cmp_author": {
        "type": "object",
        "properties": {
          "name": {"type": "string", "maxLength": 120},
          "internal_id": {"type": "string"},
          "address": {"$ref": "#/$defs/cmp_address"}
        }
      },
      "cmp_address": {
        "type": "object",
        "properties": {
          "city": {"type": "string"}
        }
      }
    }
  },
  "searchable_fields": ["author.address.city", "author.name", "published_at", "title"],
  "non_searchable_fields": ["author.internal_id"],
  "alias": "articles",
  "content_type": "document",
  "schema_key": "8qjk65j6a5s5",
  "schema_version_key": "do0k79jlmko6",
  "path": "/blog/articles",
  "actions": ["get_one", "get_many"]
}

Typical Use Cases

Build runtime validators from live schema definitions.
Show field metadata in internal tooling without calling Management API.
Pair with Router Introspection for autonomous API discovery in MCP/agent workflows.

Errors

Status	error_code	When returned
401	`authentication_required`	Missing or invalid credentials.
403	`access_denied`	Key is authenticated but lacks access to this API/collection.
404	`route_not_found`	Collection path is not connected to the Flux API.
404	`schema_not_available`	Route exists but current schema payload is unavailable (for example, unpublished or missing schema version).
405	`action_not_allowed`	Non-GET method for this endpoint (`detail: "Use GET for schema"`).

Router Introspection — discover all available routes and their contracts.
List Resources — query data that conforms to this schema.
Search — advanced querying on schema-defined fields.
Management API - Versions — publish schema versions that Flux serves.