REST API

The Infrahub REST API provides endpoints for specific operations that complement the GraphQL API. It follows OpenAPI 3.1.0 specifications.

Base URL

Production: http://localhost:8000/api All REST endpoints are prefixed with /api.

Interactive Documentation

Swagger UI: http://localhost:8000/api/docs
ReDoc: http://localhost:8000/api/redoc
OpenAPI Spec: Available at /home/daytona/workspace/source/schema/openapi.json

Authentication

REST endpoints support the same authentication methods as GraphQL: JWT Token:

curl http://localhost:8000/api/info \
  -H "Authorization: Bearer <access_token>"

API Key:

curl http://localhost:8000/api/info \
  -H "X-INFRAHUB-KEY: <api_key>"

Artifacts

Get Artifact

Retrieve a generated artifact by ID. Endpoint: GET /api/artifact/{artifact_id} Parameters:

artifact_id (path, required) - Artifact identifier
branch (query, optional) - Branch name
at (query, optional) - Timestamp for time-travel query

Example:

curl http://localhost:8000/api/artifact/abc123 \
  -H "Authorization: Bearer <token>"

Generate Artifact

Trigger artifact generation for an artifact definition. Endpoint: POST /api/artifact/generate/{artifact_definition_id} Parameters:

artifact_definition_id (path, required) - Artifact definition ID
branch (query, optional) - Branch name
at (query, optional) - Timestamp

Request Body:

{
  "nodes": ["device-id-1", "device-id-2"]
}

Example:

curl -X POST http://localhost:8000/api/artifact/generate/def123 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"nodes": ["device-1"]}'

Authentication

Authenticate with username and password. Endpoint: POST /api/auth/login Request Body:

{
  "username": "admin",
  "password": "infrahub"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Example:

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "infrahub"}'

Refresh Token

Obtain a new access token using a refresh token. Endpoint: POST /api/auth/refresh Headers:

Authorization: Bearer <refresh_token>

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Example:

curl -X POST http://localhost:8000/api/auth/refresh \
  -H "Authorization: Bearer <refresh_token>"

Logout

Invalidate the current session and refresh token. Endpoint: POST /api/auth/logout Example:

curl -X POST http://localhost:8000/api/auth/logout \
  -H "Authorization: Bearer <access_token>"

Diff Operations

Get Diff Files

Retrieve file diffs for a branch. Endpoint: GET /api/diff/files Parameters:

branch (query, optional) - Branch name
time_from (query, optional) - Start timestamp
time_to (query, optional) - End timestamp
branch_only (query, optional) - Only show branch changes (default: true)

Example:

curl "http://localhost:8000/api/diff/files?branch=feature-branch" \
  -H "Authorization: Bearer <token>"

Get Diff Artifacts

Retrieve artifact diffs for a branch. Endpoint: GET /api/diff/artifacts Parameters:

branch (query, optional) - Branch name

Example:

curl "http://localhost:8000/api/diff/artifacts?branch=feature-branch" \
  -H "Authorization: Bearer <token>"

File Operations

Get File

Retrieve a file from a Git repository. Endpoint: GET /api/file/{repository_id}/{file_path} Parameters:

repository_id (path, required) - Repository identifier
file_path (path, required) - Path to file in repository
commit (query, optional) - Specific commit hash
branch (query, optional) - Branch name
at (query, optional) - Timestamp

Example:

curl "http://localhost:8000/api/file/repo123/configs/router-01.cfg" \
  -H "Authorization: Bearer <token>"

Configuration

Get Config

Retrieve Infrahub configuration settings. Endpoint: GET /api/config Response:

{
  "main": {
    "allow_anonymous_access": false,
    "internal_address": "http://localhost:8000"
  },
  "logging": {
    "level": "INFO"
  },
  "analytics": {
    "enable": false
  },
  "experimental_features": {},
  "sso": {
    "oauth2_providers": [],
    "oidc_providers": []
  },
  "installation_type": "production",
  "policy": {}
}

Example:

curl http://localhost:8000/api/config

See /home/daytona/workspace/source/backend/infrahub/api/internal.py:44 for implementation.

Get Info

Retrieve Infrahub deployment information. Endpoint: GET /api/info Response:

{
  "deployment_id": "550e8400-e29b-41d4-a716-446655440000",
  "version": "0.15.0"
}

Example:

curl http://localhost:8000/api/info \
  -H "Authorization: Bearer <token>"

Retrieve the navigation menu structure. Endpoint: GET /api/menu Parameters:

branch (query, optional) - Branch name
at (query, optional) - Timestamp

Example:

curl "http://localhost:8000/api/menu?branch=main" \
  -H "Authorization: Bearer <token>"

GraphQL Query Execution

Execute Stored Query (POST)

Execute a stored GraphQL query by ID or name. Endpoint: POST /api/query/{query_id} Parameters:

query_id (path, required) - Query ID or name
branch (query, optional) - Branch name
at (query, optional) - Timestamp
subscribers (query, optional) - List of subscriber IDs
update_group (query, optional) - Create/update CoreGraphQLQueryGroup (default: false)

Request Body:

{
  "variables": {
    "site_name": "datacenter-1"
  }
}

Example:

curl -X POST "http://localhost:8000/api/query/get-devices-by-site" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"variables": {"site_name": "datacenter-1"}}'

Execute Stored Query (GET)

Execute a stored GraphQL query via GET request. Endpoint: GET /api/query/{query_id} Example:

curl "http://localhost:8000/api/query/list-all-devices" \
  -H "Authorization: Bearer <token>"

Schema Operations

Get Schema

Retrieve the Infrahub schema definition. Endpoint: GET /api/schema Parameters:

branch (query, optional) - Branch name
namespaces (query, optional) - Array of namespace filters

Example:

curl "http://localhost:8000/api/schema?namespaces=Infra&namespaces=Core" \
  -H "Authorization: Bearer <token>"

Get Schema Summary

Retrieve schema hash and summary information. Endpoint: GET /api/schema/summary Parameters:

branch (query, optional) - Branch name

Example:

curl "http://localhost:8000/api/schema/summary?branch=main" \
  -H "Authorization: Bearer <token>"

Get Schema by Kind

Retrieve schema definition for a specific kind. Endpoint: GET /api/schema/{schema_kind} Parameters:

schema_kind (path, required) - Schema kind (e.g., “InfraDevice”)
branch (query, optional) - Branch name

Example:

curl "http://localhost:8000/api/schema/InfraDevice" \
  -H "Authorization: Bearer <token>"

OAuth 2.0 / OIDC

OAuth 2.0 Authorization

Initiate OAuth 2.0 authorization flow. Endpoint: GET /api/oauth2/{provider_name}/authorize Parameters:

provider_name (path, required) - Provider name (e.g., “google”)
final_url (query, optional) - Redirect URL after authentication

Example:

curl "http://localhost:8000/api/oauth2/google/authorize?final_url=/dashboard"

OAuth 2.0 Token Exchange

Exchange authorization code for tokens. Endpoint: GET /api/oauth2/{provider_name}/token Parameters:

provider_name (path, required) - Provider name
state (query, required) - State parameter from authorization
code (query, required) - Authorization code

OIDC Authorization

Initiate OIDC authorization flow. Endpoint: GET /api/oidc/{provider_name}/authorize Parameters:

provider_name (path, required) - Provider name
final_url (query, optional) - Redirect URL after authentication

OIDC Token Exchange

Exchange authorization code for tokens. Endpoint: GET /api/oidc/{provider_name}/token Parameters:

provider_name (path, required) - Provider name
state (query, required) - State parameter
code (query, required) - Authorization code

Error Responses

400 Bad Request

{
  "errors": ["Request body is not a valid JSON"]
}

401 Unauthorized

{
  "errors": ["Authentication is required"]
}

404 Not Found

{
  "errors": ["The requested endpoint /api/invalid does not exist"]
}

See /home/daytona/workspace/source/backend/infrahub/api/__init__.py:75 for the catch-all 404 handler.

422 Validation Error

{
  "detail": [
    {
      "loc": ["body", "username"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Transformation Endpoints

Get Python Transform

Retrieve a Python transformation by ID. Endpoint: GET /api/transform/python/{transform_id} Parameters:

transform_id (path, required) - Transform identifier

Example:

curl http://localhost:8000/api/transform/python/my-transform \
  -H "Authorization: Bearer <token>"

Get Jinja2 Transform

Retrieve a Jinja2 transformation template by ID. Endpoint: GET /api/transform/jinja2/{transform_id} Parameters:

transform_id (path, required) - Transform identifier

Response: Plain text (Jinja2 template) Example:

curl http://localhost:8000/api/transform/jinja2/device-config \
  -H "Authorization: Bearer <token>"

Common Query Parameters

Many endpoints support these common parameters: Branch Selection:

branch - Name of the branch to use (defaults to main)

Time-Travel:

at - Timestamp in absolute or relative format
- Absolute: 2024-01-15T10:30:00Z
- Relative: -1h, -7d, -30m

Content Types

Most endpoints accept and return JSON: Request:

Content-Type: application/json

Response:

Content-Type: application/json

File endpoints return plain text: Response:

Content-Type: text/plain

Security Schemes

The OpenAPI spec defines two security schemes: HTTPBearer:

HTTPBearer:
  type: http
  scheme: bearer

APIKeyHeader:

APIKeyHeader:
  type: apiKey
  in: header
  name: X-INFRAHUB-KEY

APIs

GraphQL API

Python SDK

CLI Reference

​Base URL

​Interactive Documentation

​Authentication

​Artifacts

​Get Artifact

​Generate Artifact

​Authentication

​Login

​Refresh Token

​Logout

​Diff Operations

​Get Diff Files

​Get Diff Artifacts

​File Operations

​Get File

​Configuration

​Get Config

​Get Info

​Menu

​Get Menu

​GraphQL Query Execution

​Execute Stored Query (POST)

​Execute Stored Query (GET)

​Schema Operations

​Get Schema

​Get Schema Summary

​Get Schema by Kind

​OAuth 2.0 / OIDC

​OAuth 2.0 Authorization

​OAuth 2.0 Token Exchange

​OIDC Authorization

​OIDC Token Exchange

​Error Responses

​400 Bad Request

​401 Unauthorized

​404 Not Found

​422 Validation Error

​Transformation Endpoints

​Get Python Transform

​Get Jinja2 Transform

​Common Query Parameters

​Content Types

​Security Schemes

Build docs developers (and LLMs) love

Base URL

Interactive Documentation

Authentication

Artifacts

Get Artifact

Generate Artifact

Authentication

Login

Refresh Token

Logout

Diff Operations

Get Diff Files

Get Diff Artifacts

File Operations

Get File

Configuration

Get Config

Get Info

Menu

Get Menu

GraphQL Query Execution

Execute Stored Query (POST)

Execute Stored Query (GET)

Schema Operations

Get Schema

Get Schema Summary

Get Schema by Kind

OAuth 2.0 / OIDC

OAuth 2.0 Authorization

OAuth 2.0 Token Exchange

OIDC Authorization

OIDC Token Exchange

Error Responses

400 Bad Request

401 Unauthorized

404 Not Found

422 Validation Error

Transformation Endpoints

Get Python Transform

Get Jinja2 Transform

Common Query Parameters

Content Types

Security Schemes