EN Reference Control Plane

Control plane: all routes, request models and roles

English · Türkçe · Languages / Diller

Scope: JSON API Forge 0.5.1 · Source review: 17 September 2026 · Language: English

The control-plane prefix is /__forge/editor/v1. Project API keys cannot substitute for this session. Routes other than setup/login/register are subject to session and relevant policy/permission checks. An endpoint list grants no access; follow the remote Editor guide for network, resource and role boundaries.

HTTP and WebSocket routes

Prepend /__forge/editor/v1 to every path below. The status column reports explicit decorator success settings; handlers can also return other Response types and errors. Handler names identify the implementation at the pinned commit.

Method	Path	Handler	Success/status override
GET	/setup/status	setup_status	200
POST	/setup/founder	setup_founder	HTTP_201_CREATED
POST	/auth/login	login	200
POST	/auth/register	register	HTTP_201_CREATED
POST	/auth/logout	logout	HTTP_204_NO_CONTENT
GET	/capabilities	capabilities	200
GET	/me	me	200
PATCH	/me	update_me	200
GET	/roles	roles	200
POST	/roles	create_role	HTTP_201_CREATED
PUT	/roles/{role_id}	update_role	200
GET	/members	members	200
PUT	/members/{user_id}	update_member	HTTP_204_NO_CONTENT
POST	/invitations	invitation	HTTP_201_CREATED
GET	/projects	projects	200
POST	/projects	create_project	HTTP_201_CREATED
GET	/projects/{project_name}/documents	documents	200
GET	/projects/{project_name}/documents/{document_path:path}	read_document	200
PUT	/projects/{project_name}/documents/{document_path:path}	write_document	200
POST	/projects/{project_name}/validate	validate_project	200
GET	/projects/{project_name}/databases	databases	200
GET	/projects/{project_name}/databases/{alias}/tables/{table_name}/rows	database_rows	200
GET	/areas	areas	200
POST	/areas	create_area	HTTP_201_CREATED
GET	/areas/{area_id}/messages	messages	200
POST	/areas/{area_id}/messages	post_message	HTTP_201_CREATED
GET	/notes	notes	200
POST	/notes	create_note	HTTP_201_CREATED
POST	/areas/{area_id}/attachments	upload_attachment	HTTP_201_CREATED
GET	/areas/{area_id}/attachments	attachments	200
GET	/attachments/{attachment_id}	download_attachment	200
POST	/calls	create_call	HTTP_201_CREATED
POST	/calls/{call_id}/ticket	create_call_ticket	200
GET	/call-client/{call_id}	call_client	200
WEBSOCKET	/ws/calls/{call_id}	call_socket	WebSocket
GET	/audit	audit	200

Request body models

Runtime rules supplement schema bounds: document SHA must be new or 64 lowercase hexadecimal characters, passwords must satisfy Settings policy, and invitation roles must remain within delegation authority. A field typed as str does not mean every value is accepted.

DocumentWrite

Field	Type	Required	Default	Schema constraints
content	string	Yes	—	—
expected_sha256	string	Yes	—	minLength=3; maxLength=64

ProjectCreate

Field	Type	Required	Default	Schema constraints
name	string	Yes	—	—
slug	string	Yes	—	—

FounderCreate

Field	Type	Required	Default	Schema constraints
username	string	Yes	—	minLength=3; maxLength=32
password	string	Yes	—	minLength=1; maxLength=256
display_name	string	Yes	—	minLength=1; maxLength=80

LoginRequest

Field	Type	Required	Default	Schema constraints
username	string	Yes	—	minLength=1; maxLength=64
password	string	Yes	—	minLength=1; maxLength=256

InvitationRegistration

Field	Type	Required	Default	Schema constraints
username	string	Yes	—	minLength=3; maxLength=32
password	string	Yes	—	minLength=1; maxLength=256
display_name	string	Yes	—	minLength=1; maxLength=80
invitation	string	Yes	—	minLength=32; maxLength=512

ProfileUpdate

Field	Type	Required	Default	Schema constraints
display_name	string | null	No	null	maxLength=80
title	string | null	No	null	maxLength=120
bio	string | null	No	null	maxLength=2000
timezone	string | null	No	null	maxLength=64
status	string | null	No	null	maxLength=160

RoleWrite

Field	Type	Required	Default	Schema constraints
name	string	Yes	—	minLength=1; maxLength=64
rank	integer	Yes	—	min=1; max=999
permissions	list[string]	Yes	—	maxItems=100
document_allow	list[string]	No	[]	maxItems=100
document_deny	list[string]	No	[]	maxItems=100
database_allow	list[string]	No	[]	maxItems=100

InvitationCreate

Field	Type	Required	Default	Schema constraints
memberships	list[dict[str, string]]	Yes	—	minItems=1; maxItems=32
expires_hours	integer	No	24	min=1; max=168

MemberUpdate

Field	Type	Required	Default	Schema constraints
memberships	list[dict[str, string]]	Yes	—	maxItems=32
active	boolean	No	true	—

AreaCreate

Field	Type	Required	Default	Schema constraints
project	string	Yes	—	—
name	string	Yes	—	minLength=1; maxLength=96
description	string	No	""	maxLength=500
visibility	string	No	"open"	—
minimum_rank	integer	No	0	min=0; max=999
allowed_role_ids	list[string]	No	[]	maxItems=100

MessageCreate

Field	Type	Required	Default	Schema constraints
body	string	Yes	—	minLength=1
kind	string	No	"message"	—

NoteCreate

Field	Type	Required	Default	Schema constraints
project	string	Yes	—	—
area_id	string | null	No	null	—
title	string	Yes	—	minLength=1; maxLength=160
body	string	No	""	—
visibility	string	No	"open"	—
minimum_rank	integer	No	0	min=0; max=999
allowed_role_ids	list[string]	No	[]	maxItems=100

CallCreate

Field	Type	Required	Default	Schema constraints
area_id	string	Yes	—	—
mode	string	Yes	—	—

Application credential request models

These models belong to project security endpoints, not Editor roles or sessions.

APIKeyCreate

Field	Type	Required	Default	Schema constraints
name	string	Yes	—	minLength=1; maxLength=128
roles	list[string]	No	[]	maxItems=64
permissions	list[string]	No	[]	maxItems=256
tenant_id	string | null	No	null	maxLength=128
rate_requests	integer | null	No	null	min=1; max=10000000
rate_window_seconds	integer | null	No	null	min=1; max=86400
rate_burst	integer | null	No	null	min=1; max=10000000
expires_at	string | null	No	null	format="date-time"

JWTCreate

Field	Type	Required	Default	Schema constraints
subject	string	Yes	—	minLength=1; maxLength=256
roles	list[string]	No	[]	maxItems=64
permissions	list[string]	No	[]	maxItems=256
tenant_id	string | null	No	null	maxLength=128
exp_minutes	integer | null	No	null	min=1; max=43200

Built-in roles

Role	Rank	Permissions	Document scope	Database scope
Founder	1000	*	["*"]	["*"]
Administrator	800	*	["*"]	["*"]
Developer	600	projects.read projects.validate documents.read documents.write documents.graphs.write databases.metadata.read databases.rows.read profiles.read profiles.write.own members.read areas.read messages.read messages.write notes.read notes.write attachments.read attachments.write calls.join calls.start	["app.json","config/*.json","graphs/*.forgegraph.json"]	["*"]
Analyst	400	projects.read documents.read databases.metadata.read databases.rows.read profiles.read profiles.write.own members.read areas.read messages.read messages.write notes.read notes.write attachments.read calls.join	["*"]	["*"]
Collaborator	200	projects.read documents.read profiles.read profiles.write.own members.read areas.read messages.read messages.write notes.read notes.write attachments.read attachments.write calls.join	["*"]	[]
Viewer	100	projects.read documents.read databases.metadata.read profiles.read members.read areas.read messages.read notes.read attachments.read	["*"]	["*"]

Known permission names

• areas.manage
• areas.read
• attachments.read
• attachments.write
• audit.read
• calls.join
• calls.start
• databases.metadata.read
• databases.rows.read
• databases.undeclared.read
• documents.graphs.write
• documents.hooks.write
• documents.read
• documents.write
• invitations.manage
• members.manage
• members.read
• messages.read
• messages.write
• notes.read
• notes.write
• profiles.read
• profiles.write.own
• projects.create
• projects.read
• projects.validate
• roles.manage
• roles.read

Even higher-ranked roles containing * do not override disabled policies or founder-specific restrictions. Allow/deny and project memberships can be more restrictive than rank comparison alone.

Sources and verification

This page describes the behavior at the pinned commits below. Recheck these contracts when upgrading.

• main/framework/editor_api.py
• main/framework/editor_identity.py
• main/framework/api_models.py

---

English home · All English pages · Version maintenance