Skip to main content
Infrahub schemas define the structure of your data models. These endpoints allow you to retrieve, load, and validate schemas.

​
Get Schema

Retrieve the complete schema for a branch, including nodes, generics, profiles, and templates. 
GET /api/schema

​
Query Parameters

​
branch
string
Name of the branch to retrieve the schema from. Defaults to the main branch.
​
namespaces
array
Filter schemas by specific namespaces. If not provided, returns all namespaces.

​
Response

​
main
string
Main hash for the entire schema
​
nodes
array
List of node schemas (excluding Internal namespace)
​
generics
array
List of generic schemas (excluding Internal namespace)
​
profiles
array
List of profile schemas (excluding Internal namespace)
​
templates
array
List of template schemas (excluding Internal namespace)
​
namespaces
array
List of available namespaces in the schema

​
Example

curl -X GET "https://infrahub.example.com/api/schema?branch=main" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Schema Summary

Retrieve a summary hash of the schema for a specific branch. 
GET /api/schema/summary

​
Query Parameters

​
branch
string
Name of the branch to retrieve the schema summary from

​
Response

​
hash
object
Hash information for the schema branch, including main hash and component hashes

​
Example

curl -X GET "https://infrahub.example.com/api/schema/summary" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Schema by Kind

Retrieve a specific schema by its kind (namespace + name). 
GET /api/schema/{schema_kind}

​
Path Parameters

​
schema_kind
string
required
The kind of schema to retrieve (e.g., “CoreDevice”, “InfraPrefix”)

​
Query Parameters

​
branch
string
Name of the branch to use for the query

​
Response

Returns the schema definition including attributes, relationships, and metadata.

​
Example

curl -X GET "https://infrahub.example.com/api/schema/CoreDevice" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get JSON Schema by Kind

Retrieve a JSON Schema representation of a specific schema kind. 
GET /api/schema/json_schema/{schema_kind}

​
Path Parameters

​
schema_kind
string
required
The kind of schema to retrieve as JSON Schema

​
Query Parameters

​
branch
string
Name of the branch to use for the query

​
Response

​
$schema
string
JSON Schema version identifier (http://json-schema.org/draft-07/schema#)
​
title
string
Title of the schema
​
description
string
Description of the schema
​
type
string
Type of the schema element (typically “object”)
​
properties
object
Properties of the schema including field definitions
​
required
array
List of required properties

​
Example

curl -X GET "https://infrahub.example.com/api/schema/json_schema/CoreDevice" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Load Schema

Load or update schema definitions on a branch. This endpoint validates, migrates, and applies schema changes. 
POST /api/schema/load

​
Query Parameters

​
branch
string
Name of the branch to load the schema into. Defaults to main branch.
​
at
string
Time to use for the query, in absolute or relative format

​
Request Body

​
schemas
array
required
Array of schema definitions to load. Each schema must include a version field.

​
Response

​
hash
string
The new hash for the entire schema after loading
​
previous_hash
string
The previous hash for the entire schema before loading
​
diff
object
The modifications made to the schema
​
warnings
array
Warnings encountered while loading the schema
​
schema_updated
boolean
Indicates if the loading of the schema changed the existing schema

​
Example

curl -X POST "https://infrahub.example.com/api/schema/load" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schemas": [
      {
        "version": "1.0",
        "nodes": [
          {
            "name": "Device",
            "namespace": "Core",
            "attributes": [
              {
                "name": "name",
                "kind": "Text",
                "unique": true
              }
            ]
          }
        ]
      }
    ]
  }'

​
Check Schema

Validate schema changes without applying them. Useful for CI/CD pipelines. 
POST /api/schema/check

​
Query Parameters

​
branch
string
Name of the branch to check the schema against

​
Request Body

​
schemas
array
required
Array of schema definitions to validate

​
Response

Returns 202 Accepted if the schema is valid.
​
diff
object
The modifications that would be made to the schema
​
warnings
array
Warnings that would be generated when loading the schema

​
Example

curl -X POST "https://infrahub.example.com/api/schema/check" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schemas": [
      {
        "version": "1.0",
        "nodes": [
          {
            "name": "Device",
            "namespace": "Core",
            "attributes": [
              {
                "name": "name",
                "kind": "Text"
              }
            ]
          }
        ]
      }
    ]
  }'

​
Authentication

All schema endpoints require authentication using either:
  • Bearer Token: Include Authorization: Bearer YOUR_ACCESS_TOKEN header
  • API Key: Include X-API-KEY: YOUR_API_KEY header

​
Permissions

Loading schemas requires:
  • manage_schema global permission
  • edit_default_branch permission when modifying the default branch

Build docs developers (and LLMs) love

Get started for freeTalk to us