Studio API Reference¶

This page documents the HTTP API endpoints for Aksara Studio integration.

Endpoints Overview¶

Endpoint	Method	Description
`/studio/handshake`	GET	Complete project handshake
`/studio/context/summary`	GET	Lightweight schema summary
`/studio/health`	GET	Health check with DB status
`/studio/migrations/summary`	GET	Per-app migration statistics (v0.5.1)
`/studio/schema/handshake`	GET	JSON Schema for handshake model (v0.5.1)

Security (v0.5.1)¶

All Studio endpoints validate the incoming Origin header against studio_allowed_origins setting.

Allowed origin: Request proceeds normally
No origin header: Request allowed (same-origin, CLI, server-to-server)
Disallowed origin: 403 Forbidden response

# In aksara.conf
settings.studio_allowed_origins = [
    "https://studio.aksara.dev",
    "http://localhost:3000",
]
# Use ["*"] to allow all origins (development only!)

GET /studio/handshake¶

Complete handshake endpoint for Studio IDE. Returns everything Studio needs to understand your project.

Response¶

{
  "protocol_version": "1.0",
  "timestamp": "2024-01-15T10:30:00Z",
  "project": {
    "name": "My App",
    "version": "1.0.0",
    "aksara_version": "0.5.46",
    "python_version": "3.11.5",
    "debug_mode": true,
    "environment": "development"
  },
  "database": {
    "connected": true,
    "dialect": "postgresql",
    "pool_size": 10,
    "pool_available": 8,
    "latency_ms": null,
    "last_error": null
  },
  "capabilities": [
    "read_schema",
    "read_data",
    "write_data",
    "read_migrations",
    "apply_migrations",
    "ai_tools",
    "ai_query",
    "ai_codegen",
    "ai_patch",
    "ai_planner",
    "admin_access",
    "debug_panels"
  ],
  "checksums": {
    "schema_checksum": "abc123def456789",
    "migrations_checksum": "def456abc123789",
    "settings_checksum": "789abc123def456",
    "routes_checksum": "123def456abc789"
  },
  "endpoints": {
    "context_full": "/ai/context/full",
    "context_summary": "/studio/context/summary",
    "health": "/studio/health",
    "tools": "/ai/tools",
    "tools_mcp": "/ai/tools/mcp",
    "query_execute": "/ai/query/execute",
    "codegen_preview": "/ai/codegen/preview",
    "patch_preview": "/ai/patch/preview",
    "patch_apply": "/ai/patch/apply",
    "plan_preview": "/ai/plan/preview",
    "plan_apply": "/ai/plan/apply",
    "schema_health": "/ai/schema/health"
  },
  "metadata": {}
}

Response Fields¶

project¶

Field	Type	Description
`name`	string	Project/app name
`version`	string	Project version
`aksara_version`	string	Aksara framework version
`python_version`	string	Python runtime version
`debug_mode`	boolean	Whether app is in debug mode
`environment`	string	Environment (development, staging, production)

database¶

Field	Type	Description
`connected`	boolean	Whether database is connected
`dialect`	string	Database dialect (postgresql)
`pool_size`	integer	Current pool size
`pool_available`	integer	Available connections
`latency_ms`	float	Last query latency (if measured)
`last_error`	string	Last error message (if any)

capabilities¶

Available capabilities that Studio can use:

Capability	Description
`read_schema`	Can read model schema
`read_data`	Can read database records
`write_data`	Can write database records
`read_migrations`	Can read migration files
`apply_migrations`	Can apply migrations
`ai_tools`	AI tools endpoint available
`ai_query`	AI query execution available
`ai_codegen`	AI code generation available
`ai_patch`	AI patch operations available
`ai_planner`	AI planner available
`admin_access`	Admin interface available
`debug_panels`	Debug panels available

checksums¶

Checksums are used for cache invalidation. Studio compares these with cached values to determine if it needs to refresh data.

Field	Type	Description
`schema_checksum`	string	SHA-256 of model schema
`migrations_checksum`	string	SHA-256 of migration files
`settings_checksum`	string	SHA-256 of settings
`routes_checksum`	string	SHA-256 of routes

GET /studio/context/summary¶

Lightweight context summary without full schema. Use this for quick status checks.

Response¶

{
  "app_count": 3,
  "model_count": 5,
  "viewset_count": 3,
  "route_count": 25,
  "ai_tool_count": 15,
  "migration_count": 10,
  "pending_migrations": 0,
  "database_status": {
    "connected": true,
    "dialect": "postgresql",
    "pool_size": 10,
    "pool_available": 8,
    "latency_ms": null,
    "last_error": null
  },
  "migration_status": {
    "total": 10,
    "applied": 10,
    "pending": 0,
    "has_conflicts": false,
    "last_applied": "0010_add_tags"
  },
  "models": [
    {
      "name": "User",
      "table_name": "users",
      "field_count": 6,
      "has_relations": true
    },
    {
      "name": "Post",
      "table_name": "posts",
      "field_count": 4,
      "has_relations": true
    }
  ],
  "checksums": {
    "schema_checksum": "abc123def456789",
    "migrations_checksum": "def456abc123789",
    "settings_checksum": "789abc123def456",
    "routes_checksum": "123def456abc789"
  }
}

Response Fields¶

Field	Type	Description
`app_count`	integer	Number of installed apps (v0.5.1)
`model_count`	integer	Total registered models
`viewset_count`	integer	Total registered viewsets
`route_count`	integer	Total API routes
`ai_tool_count`	integer	Total AI tools
`migration_count`	integer	Total migrations
`pending_migrations`	integer	Unapplied migrations
`database_status`	object	Live database status (v0.5.1)
`migration_status`	object	Migration health overview (v0.5.1)
`models`	array	List of model summaries
`checksums`	object	Checksums for caching

GET /studio/health¶

Simple health check endpoint.

Response¶

{
  "status": "healthy",
  "aksara_version": "0.5.46",
  "database": {
    "connected": true,
    "dialect": "postgresql",
    "pool_size": 10,
    "pool_available": 8,
    "latency_ms": null,
    "last_error": null
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Status Values¶

Status	Description
`healthy`	Database connected, all systems go
`degraded`	Database not connected or other issues

GET /studio/migrations/summary (v0.5.1)¶

Detailed migration statistics with per-app breakdown and conflict detection.

Response¶

{
  "total_migrations": 15,
  "applied_migrations": 12,
  "pending_migrations": 3,
  "apps": [
    {
      "app_label": "auth",
      "total": 5,
      "applied": 5,
      "pending": 0,
      "has_conflicts": false,
      "head_migrations": ["0005_add_last_login"]
    },
    {
      "app_label": "blog",
      "total": 10,
      "applied": 7,
      "pending": 3,
      "has_conflicts": false,
      "head_migrations": ["0010_add_tags"]
    }
  ],
  "conflicts": [],
  "migrations_checksum": "abc123def456789",
  "last_applied": "0005_add_last_login"
}

Response Fields¶

Field	Type	Description
`total_migrations`	integer	Total migrations across all apps
`applied_migrations`	integer	Number of applied migrations
`pending_migrations`	integer	Number of pending migrations
`apps`	array	Per-app migration summaries
`conflicts`	array	Detected migration conflicts
`migrations_checksum`	string	Checksum for caching
`last_applied`	string	Name of last applied migration

Conflict Detection¶

When migrations have branched (e.g., two developers created separate migrations from the same parent), the conflicts array will contain details:

{
  "conflicts": [
    {
      "app_label": "blog",
      "heads": ["0008_feature_a", "0008_feature_b"],
      "message": "App 'blog' has 2 conflicting head migrations that need to be merged."
    }
  ]
}

GET /studio/schema/handshake (v0.5.1)¶

Returns the JSON Schema for the StudioHandshake model. Useful for:

TypeScript type generation
API documentation
Client-side validation

Response¶

{
  "$defs": {
    "StudioDatabaseStatus": {
      "properties": {
        "connected": { "type": "boolean" },
        "dialect": { "type": "string" }
      }
    }
  },
  "properties": {
    "protocol_version": {
      "default": "1.0",
      "description": "Studio protocol version",
      "type": "string"
    },
    "project": { "$ref": "#/$defs/StudioProjectInfo" },
    "database": { "$ref": "#/$defs/StudioDatabaseStatus" }
  },
  "required": ["project", "database", "capabilities", "checksums"],
  "title": "StudioHandshake",
  "type": "object"
}

Usage Example (TypeScript)¶

// Generate types from JSON Schema
import { compile } from 'json-schema-to-typescript';

const response = await fetch('/studio/schema/handshake');
const schema = await response.json();
const types = await compile(schema, 'StudioHandshake');

Using with curl¶

Test Handshake¶

curl http://localhost:8000/studio/handshake | jq

Check Health¶

curl http://localhost:8000/studio/health | jq

Get Summary¶

curl http://localhost:8000/studio/context/summary | jq

Get Migration Summary (v0.5.1)¶

curl http://localhost:8000/studio/migrations/summary | jq

Get JSON Schema (v0.5.1)¶

curl http://localhost:8000/studio/schema/handshake | jq

Full Context¶

For the complete application context including full schema, use the AI context endpoint:

curl http://localhost:8000/ai/context/full | jq

This returns the full AiFullContext which includes:

Complete model definitions with all fields
ViewSet definitions with all actions
Route information
Migration history
Admin configuration
AI tool registry

See AI Context Documentation for details.