{
  "openapi": "3.1.0",
  "info": {
    "title": "EngineForge Public API",
    "version": "1.0.0",
    "summary": "Read the EngineForge Crew, tool, engine-bridge, and model surface.",
    "description": "EngineForge is an AI platform for game development that works inside existing Unity and Godot projects. This description covers the endpoints that answer without credentials, so an agent can discover which Crew specialists exist, what they are able to do inside an engine, and which models can run a task. All operations are read-only GET requests, return JSON, and allow cross-origin requests from any origin.",
    "contact": {
      "name": "EngineForge Support",
      "email": "support@engineforge.ai",
      "url": "https://engineforge.ai/contact"
    },
    "termsOfService": "https://engineforge.ai/privacy"
  },
  "servers": [
    {
      "url": "https://engineforge.ai",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "EngineForge developer resources",
    "url": "https://engineforge.ai/developers"
  },
  "tags": [
    {
      "name": "discovery",
      "description": "Read-only endpoints describing the EngineForge Crew, tools, engines, and models."
    }
  ],
  "paths": {
    "/api/models": {
      "get": {
        "operationId": "listModels",
        "tags": [
          "discovery"
        ],
        "summary": "List the language models EngineForge can run a task on",
        "description": "Returns every model EngineForge exposes for task execution, with the context window, maximum output tokens, image support, reasoning support, and a relative cost tier. No pricing and no credentials are involved. Use it to decide which model to name when describing an EngineForge workflow.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "List the language models EngineForge can run a task on",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelListResponse"
                }
              }
            }
          },
          "405": {
            "description": "The endpoint is read-only and answers GET and OPTIONS only.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The endpoint could not read its upstream data source.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/agents": {
      "get": {
        "operationId": "listAgents",
        "tags": [
          "discovery"
        ],
        "summary": "List the published Crew specialists",
        "description": "Returns the enabled EngineForge Crew specialists — the roles a task can be assigned to — with each role's name, description, when-to-use guidance, and capability groups. Use it to answer which specialist handles a given kind of game-development work.",
        "parameters": [
          {
            "name": "v",
            "in": "query",
            "required": false,
            "description": "Version the caller already holds. When it matches the currently served version the endpoint answers 304 Not Modified with no body.",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List the published Crew specialists",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentListResponse"
                }
              }
            }
          },
          "304": {
            "description": "The caller already holds the currently served version. No body is returned."
          },
          "405": {
            "description": "The endpoint is read-only and answers GET and OPTIONS only.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The endpoint could not read its upstream data source.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/tools": {
      "get": {
        "operationId": "listTools",
        "tags": [
          "discovery"
        ],
        "summary": "List the native tools available to Crew specialists",
        "description": "Returns the enabled native tools with their descriptions and capability groups, filtered to the tools a given EngineForge build can run. Use it to answer what an EngineForge specialist is able to do inside a project.",
        "parameters": [
          {
            "name": "v",
            "in": "query",
            "required": false,
            "description": "Version the caller already holds. When it matches the currently served version the endpoint answers 304 Not Modified with no body.",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "ideVersion",
            "in": "query",
            "required": false,
            "description": "EngineForge build the caller is running, as a dotted version such as 1.4.0. Rows that require a newer build are filtered out of the response.",
            "schema": {
              "type": "string",
              "pattern": "^\\d+(\\.\\d+)*$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List the native tools available to Crew specialists",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ToolListResponse"
                }
              }
            }
          },
          "304": {
            "description": "The caller already holds the currently served version. No body is returned."
          },
          "405": {
            "description": "The endpoint is read-only and answers GET and OPTIONS only.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The endpoint could not read its upstream data source.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/bridge-categories": {
      "get": {
        "operationId": "listBridgeCategories",
        "tags": [
          "discovery"
        ],
        "summary": "List the engine bridge actions for Unity or Godot",
        "description": "Returns the editor and runtime actions EngineForge can perform inside a connected Unity or Godot editor, grouped by category, with each action's parameters and whether it is read-only. Use it to answer what EngineForge can do inside a specific engine.",
        "parameters": [
          {
            "name": "engine",
            "in": "query",
            "required": false,
            "description": "Restrict the response to one engine. Omit it to receive both.",
            "schema": {
              "type": "string",
              "enum": [
                "unity",
                "godot"
              ]
            }
          },
          {
            "name": "v",
            "in": "query",
            "required": false,
            "description": "Version the caller already holds. When it matches the currently served version the endpoint answers 304 Not Modified with no body.",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "ideVersion",
            "in": "query",
            "required": false,
            "description": "EngineForge build the caller is running, as a dotted version such as 1.4.0. Rows that require a newer build are filtered out of the response.",
            "schema": {
              "type": "string",
              "pattern": "^\\d+(\\.\\d+)*$"
            }
          },
          {
            "name": "engineVersion",
            "in": "query",
            "required": false,
            "description": "Version of the connected engine, such as 6.0.1. Categories outside their supported engine range are filtered out.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List the engine bridge actions for Unity or Godot",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BridgeCategoryListResponse"
                }
              }
            }
          },
          "304": {
            "description": "The caller already holds the currently served version. No body is returned."
          },
          "405": {
            "description": "The endpoint is read-only and answers GET and OPTIONS only.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The endpoint could not read its upstream data source.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Structured error envelope returned by every public EngineForge endpoint. Never an HTML page.",
        "required": [
          "error",
          "code",
          "message",
          "hint",
          "documentation",
          "status"
        ],
        "additionalProperties": false,
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable message. Retained for existing clients; identical to message."
          },
          "code": {
            "type": "string",
            "description": "Stable machine-readable error code to branch on.",
            "enum": [
              "not_found",
              "method_not_allowed",
              "upstream_unavailable",
              "internal_error"
            ]
          },
          "message": {
            "type": "string",
            "description": "Human-readable description of what went wrong."
          },
          "hint": {
            "type": "string",
            "description": "What the caller should do next to recover."
          },
          "documentation": {
            "type": "string",
            "format": "uri",
            "description": "Link to this OpenAPI description."
          },
          "status": {
            "type": "integer",
            "description": "HTTP status code, repeated in the body."
          }
        }
      },
      "Model": {
        "type": "object",
        "description": "One language model EngineForge can run a task on.",
        "required": [
          "provider",
          "id",
          "name",
          "contextWindow",
          "maxOutputTokens",
          "supportsImages",
          "costTier",
          "recommended",
          "reasoning",
          "bestFor"
        ],
        "properties": {
          "provider": {
            "type": "string",
            "description": "Model provider, such as anthropic, openai, or deepseek."
          },
          "id": {
            "type": "string",
            "description": "Model identifier to send when starting a task."
          },
          "name": {
            "type": "string",
            "description": "Display name shown in the EngineForge model picker."
          },
          "contextWindow": {
            "type": "integer",
            "description": "Maximum input tokens the model accepts."
          },
          "maxOutputTokens": {
            "type": "integer",
            "description": "Maximum tokens the model can produce in one response."
          },
          "supportsImages": {
            "type": "boolean",
            "description": "Whether the model accepts image input."
          },
          "costTier": {
            "type": "integer",
            "enum": [
              1,
              2,
              3
            ],
            "description": "Relative cost band: 1 is least expensive, 3 is most expensive. Not a price."
          },
          "recommended": {
            "type": "boolean",
            "description": "Whether EngineForge recommends this model as a default choice."
          },
          "reasoning": {
            "type": "boolean",
            "description": "Whether the model supports configurable reasoning effort."
          },
          "bestFor": {
            "type": "string",
            "description": "Short guidance on the kind of task this model suits."
          }
        }
      },
      "ModelListResponse": {
        "type": "object",
        "required": [
          "models",
          "default"
        ],
        "properties": {
          "models": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Model"
            }
          },
          "default": {
            "type": "string",
            "description": "Identifier of the model EngineForge selects when none is chosen."
          }
        }
      },
      "Agent": {
        "type": "object",
        "description": "One EngineForge Crew specialist.",
        "required": [
          "id",
          "name",
          "version",
          "minIdeVersion"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable specialist identifier."
          },
          "name": {
            "type": "string",
            "description": "Specialist display name, such as Engineer or Level Designer."
          },
          "description": {
            "type": "string",
            "description": "What this specialist is responsible for."
          },
          "whenToUse": {
            "type": "string",
            "description": "When a task should be routed to this specialist."
          },
          "capabilities": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Capability groups this specialist may use, such as read, edit, command, or bridge."
          },
          "version": {
            "type": "integer",
            "description": "Row version, used with the v query parameter."
          },
          "minIdeVersion": {
            "type": [
              "string",
              "null"
            ],
            "description": "Lowest EngineForge build that can run this specialist."
          }
        }
      },
      "AgentListResponse": {
        "type": "object",
        "required": [
          "agents",
          "version"
        ],
        "properties": {
          "agents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Agent"
            }
          },
          "version": {
            "type": "integer",
            "description": "Highest specialist version currently served."
          }
        }
      },
      "Tool": {
        "type": "object",
        "description": "One native tool a Crew specialist can call.",
        "required": [
          "name",
          "description",
          "groups"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Tool name as the specialist calls it."
          },
          "description": {
            "type": "string",
            "description": "What the tool does."
          },
          "groups": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Capability groups that grant this tool, such as read, edit, or command."
          }
        }
      },
      "ToolListResponse": {
        "type": "object",
        "required": [
          "tools",
          "version"
        ],
        "properties": {
          "tools": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Tool"
            }
          },
          "version": {
            "type": "integer",
            "description": "Currently served tool-catalogue version."
          }
        }
      },
      "BridgeAction": {
        "type": "object",
        "description": "One action EngineForge can perform inside a connected engine editor.",
        "required": [
          "description",
          "params",
          "required",
          "read_only"
        ],
        "properties": {
          "description": {
            "type": "string",
            "description": "What the action does in the editor or running game."
          },
          "params": {
            "type": "object",
            "description": "Parameter name to its type and description.",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "string"
                  ]
                },
                "description": {
                  "type": "string"
                }
              }
            }
          },
          "required": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Parameter names that must be supplied."
          },
          "read_only": {
            "type": "boolean",
            "description": "Whether the action only observes the project rather than changing it."
          }
        }
      },
      "BridgeCategory": {
        "type": "object",
        "required": [
          "engine",
          "category",
          "description",
          "actions"
        ],
        "properties": {
          "engine": {
            "type": "string",
            "enum": [
              "unity",
              "godot"
            ],
            "description": "Engine this category belongs to."
          },
          "category": {
            "type": "string",
            "description": "Category name, such as scene or runtime."
          },
          "description": {
            "type": "string",
            "description": "What this group of actions covers."
          },
          "actions": {
            "type": "object",
            "description": "Action name to its definition.",
            "additionalProperties": {
              "$ref": "#/components/schemas/BridgeAction"
            }
          },
          "engineVersionRange": {
            "type": [
              "string",
              "null"
            ],
            "description": "Engine versions this category applies to."
          }
        }
      },
      "BridgeCategoryListResponse": {
        "type": "object",
        "required": [
          "categories",
          "version"
        ],
        "properties": {
          "categories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BridgeCategory"
            }
          },
          "version": {
            "type": "integer",
            "description": "Currently served bridge-category version."
          }
        }
      }
    }
  }
}