EN HTTP Endpoint Map

HTTP endpoint map and contracts

English · Türkçe · Languages / Diller

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

P is your project's actual api_prefix; R is a resource path, D a data-source path and E an event-channel path. The following route families are generated when their features are enabled. Two projects must not claim the same route prefix.

Area	HTTP / path pattern	Condition / explanation
Project metadata	GET P/meta	Security and policy apply
OpenAPI	GET P/_openapi.json	docs_enabled
Swagger/ReDoc	GET P/_docs, GET P/_redoc	docs_enabled
Create/list API keys	POST, GET P/admin/api-keys	Bootstrap or authorized persistent principal, as applicable
Revoke API key	DELETE P/admin/api-keys/{key_id}	Authorized principal
Issue JWT	POST P/admin/jwt	Local JWT issuance enabled
SQL/Mongo list/create	GET, POST P/R	allowed_actions
SQL/Mongo item	GET, PATCH, PUT, DELETE P/R/{item_id}	allowed_actions, tenant/owner policy
Count	GET P/R/_count	List action; SQL also requires count_enabled
SQL batch create	POST P/R/_batch	Create action and batch_enabled
SQL operation	Configured method + P/<path>	Default path is rpc/<name>
Read data source	Configured method + P/D	Static/file/HTTP contract
Write JSON file	POST P/D, PATCH/PUT/DELETE P/D/{item_id}	Explicit write policy and file backend
Custom endpoint	Configured method + P/<path>	Python handler/dependency/response configuration
Publish event	POST P/E	Publish permission
SSE	GET P/E/stream	SSE enabled and subscribe permission
WebSocket	WS P/E/ws	WS enabled and transport authentication policy
Upload media	POST P/media	Media enabled; multipart file
Batch media	POST P/media/_batch	Multipart files; per-item results
Media bytes	GET P/media/{media_id}	Read/owner policy or valid signed token
Media metadata	GET P/media/{media_id}/meta	Authorized metadata access
Signed URL	POST P/media/{media_id}/signed-url	Signing key and policy
Delete media	DELETE P/media/{media_id}	Delete/owner policy and metadata consistency

webhook_docs generates OpenAPI webhook definitions; it does not imply a webhook delivery service or receiving endpoint. Global health/readiness/metrics paths are covered in observability, and management/team routes in the control-plane reference.

Get your application's exact route list

forge routes
forge openapi --output forge-openapi.json

Use forge openapi --help to confirm the option for your installed version. You can also retrieve HTTP OpenAPI from P/_openapi.json. Root documentation and project documentation can have different scopes.

Request and response rules

• Authentication, data permissions and input schemas are separate checks. A schema-valid request is not automatically authorized.
• PUT and PATCH are not interchangeable; follow the CRUD contract.
• Do not assume list responses contain total; counting can use a separate endpoint. Do not use offset helpers for cursor pagination.
• RPC transactions and idempotency do not automatically cover every CRUD operation or HTTP hook.
• Record an HTTP error's status, body and request ID together. Do not make detail text your program's only stable contract.
• Response headers such as X-Request-ID, X-Forge-Cache and X-Forge-Idempotent-Replay provide diagnostics/replay information, not access permissions. Check the corresponding feature code for exact header behavior.
• SDK helpers follow the standard /api/<project>/v1 convention. Use low-level request for a custom prefix or method.

Common status codes

Status	Typical interpretation
400	Invalid request combination or operation input
401	Missing, invalid, expired or consumed authentication
403	Authenticated but forbidden by permission or policy
404	Missing route/item, or existence hidden by policy
409	Conflict, including an incompatible idempotency replay
413	Request body or upload exceeds a configured limit
422	Request/model/schema validation failure
429	Rate limit or protective blocking
503	Dependency unavailable, readiness failure or temporary capacity problem

These are diagnostic categories, not an exhaustive status-code contract for every endpoint. Inspect the route, project policy and actual response together.

Sources and verification

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

• main/framework/routers/project.py
• main/framework/factory.py
• main/framework/cli.py
• main/docs/32-API-Semantics-and-HTTP-Contracts.md

---

English home · All English pages · Version maintenance