{
  "openapi": "3.1.0",
  "info": {
    "title": "dcupl REST API (RAPI)",
    "version": "3.1.0",
    "summary": "Query a deployed dcupl application: items, facets, aggregations, pivots, suggestions, MCP.",
    "description": "Every dcupl application deployed as a REST API (RAPI) instance answers this API: filtered queries, facets, aggregations, pivots, suggestions and metadata over the instance’s data models, the project’s scripted endpoints, and an MCP endpoint for AI agents. The data is read-only and loaded once when the instance starts.\n\n**When to use it:** to read a deployed dcupl application from a backend, an app or an agent over HTTP — product catalogs, master data, any tabular data a project models. Not for writing data, and not for building the project itself (use the dcupl CLI and the Console for that).\n\n**Base URL:** `https://run.dcupl.com/runner/{runnerKey}/instance/{instanceKey}` on a dcupl-hosted runner, or `{runnerUrl}/instance/{instanceKey}` on any runner. The instance key is the one the Console shows in the runner tab’s **Instance** column: `{projectId}-{template key}`.\n\n**Authentication:** the instance’s API key in the `api-key` header (or the `api-key` query parameter). A template without a key deploys an open instance. `GET /swagger-json` needs no key.\n\n**Models:** there are no routes per model. `GET /overview` lists the models; every query route names one in `modelKey`. Each instance also serves its own OpenAPI document (`GET /swagger-json`) that adds one operation per scripted endpoint of its template.\n\n**v-Guard:** when the template turns it on, every data request needs the current `v` from `GET /status`; after `400 Invalid v parameter`, read `v` again and retry.",
    "contact": {
      "name": "dcupl",
      "email": "office@dcupl.com",
      "url": "https://dcupl.com"
    }
  },
  "externalDocs": {
    "url": "https://docs.dcupl.com/console/rapi",
    "description": "RAPI (REST API) documentation"
  },
  "servers": [
    {
      "url": "https://run.dcupl.com/runner/{runnerKey}/instance/{instanceKey}",
      "description": "An instance on a dcupl-hosted runner.",
      "variables": {
        "runnerKey": {
          "default": "dcupl-runner-01",
          "description": "The runner the instance is deployed to (the runner tab in the Console)."
        },
        "instanceKey": {
          "default": "your-project-id-orders-api",
          "description": "The instance key: `{projectId}-{template key}`, as the runner tab’s Instance column shows it (a runner set up without the prefix uses the bare template key)."
        }
      }
    },
    {
      "url": "{runnerUrl}/instance/{instanceKey}",
      "description": "An instance on any runner, e.g. a self-hosted one.",
      "variables": {
        "runnerUrl": {
          "default": "https://run.dcupl.com/runner/dcupl-runner-01",
          "description": "The runner URL shown on the runner tab in the Console, without a trailing slash."
        },
        "instanceKey": {
          "default": "your-project-id-orders-api",
          "description": "The instance key: `{projectId}-{template key}`."
        }
      }
    }
  ],
  "security": [
    {
      "api-key": []
    },
    {
      "api-key-query": []
    },
    {}
  ],
  "tags": [
    {
      "name": "Query",
      "description": "Read the data: items, facets, aggregations, pivots, suggestions, metadata."
    },
    {
      "name": "Instance",
      "description": "What the instance loaded, its version hash `v`, its call counters."
    },
    {
      "name": "Scripted endpoints",
      "description": "Routes the template declares, answered by project scripts."
    },
    {
      "name": "MCP",
      "description": "The Model Context Protocol endpoint for AI agents."
    },
    {
      "name": "API description",
      "description": "The instance’s own OpenAPI document."
    }
  ],
  "paths": {
    "/query": {
      "post": {
        "operationId": "postQuery",
        "tags": [
          "Query"
        ],
        "summary": "Query items of a model",
        "description": "Returns the items of one model that match the conditions, with projection, sort and paging. A plain `find` string matches the whole value case-sensitively; use \"/…/\" with `options.regexFlags: \"i\"` for a case-insensitive substring. An empty result usually means a wrong value or case: check the stored values with `postFacet` or `postSuggest` first. Runs `dcupl.query.execute()` on the instance. Answers are cacheable for an hour (`cache-control: private, max-age=3600`; `public` on an open instance; `no-store` on errors).",
        "externalDocs": {
          "url": "https://docs.dcupl.com/console/rapi#query-endpoints",
          "description": "Query endpoints"
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/VGuard"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QueryOptions"
              },
              "example": {
                "modelKey": "Article",
                "queries": [
                  {
                    "attribute": "category",
                    "operator": "eq",
                    "value": "Football"
                  }
                ],
                "projection": {
                  "productName": true,
                  "price": true
                },
                "sort": {
                  "attributes": [
                    "price"
                  ],
                  "order": [
                    "DESC"
                  ]
                },
                "start": 0,
                "count": 10
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The matching items.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueryResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "get": {
        "operationId": "getQuery",
        "tags": [
          "Query"
        ],
        "summary": "Query items of a model (GET)",
        "description": "The GET form of `postQuery`: the same options as a JSON string in the `data` query parameter, for clients and caches that need a plain URL. Prefer `postQuery` otherwise. Answers are cacheable for an hour (`cache-control: private, max-age=3600`; `public` on an open instance; `no-store` on errors).",
        "externalDocs": {
          "url": "https://docs.dcupl.com/console/rapi#query-endpoints",
          "description": "Query endpoints"
        },
        "parameters": [
          {
            "name": "data",
            "in": "query",
            "required": true,
            "description": "The options of `postQuery` (schema QueryOptions) serialised as a JSON string, URL-encoded.",
            "schema": {
              "type": "string",
              "contentMediaType": "application/json"
            },
            "example": "{\"modelKey\":\"Article\",\"queries\":[{\"attribute\":\"category\",\"operator\":\"eq\",\"value\":\"Football\"}],\"projection\":{\"productName\":true,\"price\":true},\"sort\":{\"attributes\":[\"price\"],\"order\":[\"DESC\"]},\"start\":0,\"count\":10}"
          },
          {
            "$ref": "#/components/parameters/VGuard"
          }
        ],
        "responses": {
          "200": {
            "description": "The matching items.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueryResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/facet": {
      "post": {
        "operationId": "postFacet",
        "tags": [
          "Query"
        ],
        "summary": "Count the values of an attribute",
        "description": "Returns the distinct values of one attribute with their item counts, optionally within a filter — for breakdowns, and to see which values really exist before filtering on one. Runs `dcupl.fn.facets()`. Answers are cacheable for an hour (`cache-control: private, max-age=3600`; `public` on an open instance; `no-store` on errors).",
        "externalDocs": {
          "url": "https://docs.dcupl.com/console/rapi#query-endpoints",
          "description": "Query endpoints"
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/VGuard"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FacetRequest"
              },
              "example": {
                "modelKey": "Article",
                "options": {
                  "attribute": "category",
                  "sort": "size-desc",
                  "count": 20
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "One entry per value.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FacetResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "get": {
        "operationId": "getFacet",
        "tags": [
          "Query"
        ],
        "summary": "Count the values of an attribute (GET)",
        "description": "The GET form of `postFacet`: the same options as a JSON string in the `data` query parameter, for clients and caches that need a plain URL. Prefer `postFacet` otherwise. Answers are cacheable for an hour (`cache-control: private, max-age=3600`; `public` on an open instance; `no-store` on errors).",
        "externalDocs": {
          "url": "https://docs.dcupl.com/console/rapi#query-endpoints",
          "description": "Query endpoints"
        },
        "parameters": [
          {
            "name": "data",
            "in": "query",
            "required": true,
            "description": "The options of `postFacet` (schema FacetRequest) serialised as a JSON string, URL-encoded.",
            "schema": {
              "type": "string",
              "contentMediaType": "application/json"
            },
            "example": "{\"modelKey\":\"Article\",\"options\":{\"attribute\":\"category\",\"sort\":\"size-desc\",\"count\":20}}"
          },
          {
            "$ref": "#/components/parameters/VGuard"
          }
        ],
        "responses": {
          "200": {
            "description": "One entry per value.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FacetResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/aggregate": {
      "post": {
        "operationId": "postAggregate",
        "tags": [
          "Query"
        ],
        "summary": "Aggregate an attribute",
        "description": "Computes `sum`, `avg`, `count`, `min`, `max`, `distinct` or `group` over one attribute, optionally within a filter. Use it for totals instead of reading items. Runs `dcupl.fn.aggregate()`. Answers are cacheable for an hour (`cache-control: private, max-age=3600`; `public` on an open instance; `no-store` on errors).",
        "externalDocs": {
          "url": "https://docs.dcupl.com/console/rapi#query-endpoints",
          "description": "Query endpoints"
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/VGuard"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AggregateRequest"
              },
              "example": {
                "modelKey": "Article",
                "options": {
                  "attribute": "price",
                  "types": [
                    "min",
                    "max",
                    "avg"
                  ]
                },
                "query": {
                  "modelKey": "Article",
                  "queries": [
                    {
                      "attribute": "category",
                      "operator": "eq",
                      "value": "Football"
                    }
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The requested aggregations.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Aggregation"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "get": {
        "operationId": "getAggregate",
        "tags": [
          "Query"
        ],
        "summary": "Aggregate an attribute (GET)",
        "description": "The GET form of `postAggregate`: the same options as a JSON string in the `data` query parameter, for clients and caches that need a plain URL. Prefer `postAggregate` otherwise. Answers are cacheable for an hour (`cache-control: private, max-age=3600`; `public` on an open instance; `no-store` on errors).",
        "externalDocs": {
          "url": "https://docs.dcupl.com/console/rapi#query-endpoints",
          "description": "Query endpoints"
        },
        "parameters": [
          {
            "name": "data",
            "in": "query",
            "required": true,
            "description": "The options of `postAggregate` (schema AggregateRequest) serialised as a JSON string, URL-encoded.",
            "schema": {
              "type": "string",
              "contentMediaType": "application/json"
            },
            "example": "{\"modelKey\":\"Article\",\"options\":{\"attribute\":\"price\",\"types\":[\"min\",\"max\",\"avg\"]},\"query\":{\"modelKey\":\"Article\",\"queries\":[{\"attribute\":\"category\",\"operator\":\"eq\",\"value\":\"Football\"}]}}"
          },
          {
            "$ref": "#/components/parameters/VGuard"
          }
        ],
        "responses": {
          "200": {
            "description": "The requested aggregations.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Aggregation"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/pivot": {
      "post": {
        "operationId": "postPivot",
        "tags": [
          "Query"
        ],
        "summary": "Build a pivot table",
        "description": "Groups the items by row and column attributes and aggregates values per cell, optionally within a filter: two-dimensional breakdowns in one call. Runs `dcupl.fn.pivot()`. Answers are cacheable for an hour (`cache-control: private, max-age=3600`; `public` on an open instance; `no-store` on errors).",
        "externalDocs": {
          "url": "https://docs.dcupl.com/console/rapi#query-endpoints",
          "description": "Query endpoints"
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/VGuard"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PivotRequest"
              },
              "example": {
                "modelKey": "Article",
                "options": {
                  "rows": [
                    {
                      "attribute": "category"
                    }
                  ],
                  "columns": [
                    {
                      "attribute": "vendor.country"
                    }
                  ],
                  "values": [
                    {
                      "attribute": "price",
                      "types": [
                        "sum"
                      ]
                    }
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The pivot tree.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PivotResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "get": {
        "operationId": "getPivot",
        "tags": [
          "Query"
        ],
        "summary": "Build a pivot table (GET)",
        "description": "The GET form of `postPivot`: the same options as a JSON string in the `data` query parameter, for clients and caches that need a plain URL. Prefer `postPivot` otherwise. Answers are cacheable for an hour (`cache-control: private, max-age=3600`; `public` on an open instance; `no-store` on errors).",
        "externalDocs": {
          "url": "https://docs.dcupl.com/console/rapi#query-endpoints",
          "description": "Query endpoints"
        },
        "parameters": [
          {
            "name": "data",
            "in": "query",
            "required": true,
            "description": "The options of `postPivot` (schema PivotRequest) serialised as a JSON string, URL-encoded.",
            "schema": {
              "type": "string",
              "contentMediaType": "application/json"
            },
            "example": "{\"modelKey\":\"Article\",\"options\":{\"rows\":[{\"attribute\":\"category\"}],\"columns\":[{\"attribute\":\"vendor.country\"}],\"values\":[{\"attribute\":\"price\",\"types\":[\"sum\"]}]}}"
          },
          {
            "$ref": "#/components/parameters/VGuard"
          }
        ],
        "responses": {
          "200": {
            "description": "The pivot tree.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PivotResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/suggest": {
      "post": {
        "operationId": "postSuggest",
        "tags": [
          "Query"
        ],
        "summary": "Complete a term to stored values",
        "description": "Returns the stored values of an attribute that match a partial input — to resolve a term to the exact value before filtering on it. A plain value is a case-insensitive prefix. Runs `dcupl.fn.suggest()`. Answers are cacheable for an hour (`cache-control: private, max-age=3600`; `public` on an open instance; `no-store` on errors).",
        "externalDocs": {
          "url": "https://docs.dcupl.com/console/rapi#query-endpoints",
          "description": "Query endpoints"
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/VGuard"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SuggestRequest"
              },
              "example": {
                "modelKey": "Article",
                "options": {
                  "attribute": "productName",
                  "value": "bask",
                  "max": 5
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The matching values.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuggestResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "get": {
        "operationId": "getSuggest",
        "tags": [
          "Query"
        ],
        "summary": "Complete a term to stored values (GET)",
        "description": "The GET form of `postSuggest`: the same options as a JSON string in the `data` query parameter, for clients and caches that need a plain URL. Prefer `postSuggest` otherwise. Answers are cacheable for an hour (`cache-control: private, max-age=3600`; `public` on an open instance; `no-store` on errors).",
        "externalDocs": {
          "url": "https://docs.dcupl.com/console/rapi#query-endpoints",
          "description": "Query endpoints"
        },
        "parameters": [
          {
            "name": "data",
            "in": "query",
            "required": true,
            "description": "The options of `postSuggest` (schema SuggestRequest) serialised as a JSON string, URL-encoded.",
            "schema": {
              "type": "string",
              "contentMediaType": "application/json"
            },
            "example": "{\"modelKey\":\"Article\",\"options\":{\"attribute\":\"productName\",\"value\":\"bask\",\"max\":5}}"
          },
          {
            "$ref": "#/components/parameters/VGuard"
          }
        ],
        "responses": {
          "200": {
            "description": "The matching values.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuggestResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/metadata": {
      "post": {
        "operationId": "postMetadata",
        "tags": [
          "Query"
        ],
        "summary": "Read the metadata of a model",
        "description": "Returns a model's total and filtered item counts and its attributes with their types. Runs `dcupl.fn.metadata()`. Answers are cacheable for an hour (`cache-control: private, max-age=3600`; `public` on an open instance; `no-store` on errors).",
        "externalDocs": {
          "url": "https://docs.dcupl.com/console/rapi#query-endpoints",
          "description": "Query endpoints"
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/VGuard"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MetadataRequest"
              },
              "example": {
                "modelKey": "Article",
                "query": {
                  "modelKey": "Article",
                  "queries": [
                    {
                      "attribute": "category",
                      "operator": "eq",
                      "value": "Football"
                    }
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The model metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelMetadata"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "get": {
        "operationId": "getMetadata",
        "tags": [
          "Query"
        ],
        "summary": "Read the metadata of a model (GET)",
        "description": "The GET form of `postMetadata`: the same options as a JSON string in the `data` query parameter, for clients and caches that need a plain URL. Prefer `postMetadata` otherwise. Answers are cacheable for an hour (`cache-control: private, max-age=3600`; `public` on an open instance; `no-store` on errors).",
        "externalDocs": {
          "url": "https://docs.dcupl.com/console/rapi#query-endpoints",
          "description": "Query endpoints"
        },
        "parameters": [
          {
            "name": "data",
            "in": "query",
            "required": true,
            "description": "The options of `postMetadata` (schema MetadataRequest) serialised as a JSON string, URL-encoded.",
            "schema": {
              "type": "string",
              "contentMediaType": "application/json"
            },
            "example": "{\"modelKey\":\"Article\",\"query\":{\"modelKey\":\"Article\",\"queries\":[{\"attribute\":\"category\",\"operator\":\"eq\",\"value\":\"Football\"}]}}"
          },
          {
            "$ref": "#/components/parameters/VGuard"
          }
        ],
        "responses": {
          "200": {
            "description": "The model metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelMetadata"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/status": {
      "get": {
        "operationId": "getStatus",
        "tags": [
          "Instance"
        ],
        "summary": "Read the instance status and its v",
        "description": "Whether the instance is ready, what it loaded, and the version hash `v` that v-Guard checks. Call it first: a 403 here means the API key or the instance key is wrong. Not subject to v-Guard.",
        "externalDocs": {
          "url": "https://docs.dcupl.com/console/rapi#status-endpoint",
          "description": "Status endpoint"
        },
        "responses": {
          "200": {
            "description": "The instance status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InstanceStatus"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/overview": {
      "get": {
        "operationId": "getOverview",
        "tags": [
          "Instance"
        ],
        "summary": "List the models and their item counts",
        "description": "The models of the loaded application with their item counts: the `modelKey` values every query route takes. Not subject to v-Guard.",
        "externalDocs": {
          "url": "https://docs.dcupl.com/console/rapi#overview-endpoint",
          "description": "Overview endpoint"
        },
        "responses": {
          "200": {
            "description": "The models.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Overview"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/details": {
      "get": {
        "operationId": "getDetails",
        "tags": [
          "Instance"
        ],
        "summary": "Read status, memory and call counters",
        "description": "The status plus the heap figures of the instance and its call counters. Not subject to v-Guard.",
        "externalDocs": {
          "url": "https://docs.dcupl.com/console/rapi#details-and-invocations",
          "description": "Details and invocations"
        },
        "responses": {
          "200": {
            "description": "The instance details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InstanceDetails"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/invocations": {
      "get": {
        "operationId": "getInvocations",
        "tags": [
          "Instance"
        ],
        "summary": "Read the call counters",
        "description": "The call counters of the instance, per action. Needs the current `v` while v-Guard is on. MCP calls count as `mcp:<tool>` next to the action they trigger, so summing every action double-counts agent traffic.",
        "externalDocs": {
          "url": "https://docs.dcupl.com/console/rapi#details-and-invocations",
          "description": "Details and invocations"
        },
        "parameters": [
          {
            "name": "action",
            "in": "query",
            "required": false,
            "description": "Select one action, e.g. `query`, `endpoint:orders/:id` or `mcp:query`; omitted = all.",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/VGuard"
          }
        ],
        "responses": {
          "200": {
            "description": "The call counters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Invocations"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/swagger-json": {
      "get": {
        "operationId": "getOpenApiDocument",
        "tags": [
          "API description"
        ],
        "summary": "Read the instance's own OpenAPI document",
        "description": "The OpenAPI 3.0 document this instance serves: the routes above plus one operation per scripted endpoint of its template (with its path parameters and description). Needs no API key; it contains no secrets. The Swagger UI for it is `GET /swagger`.",
        "externalDocs": {
          "url": "https://docs.dcupl.com/console/rapi#swagger-documentation",
          "description": "Swagger documentation"
        },
        "security": [],
        "responses": {
          "200": {
            "description": "The OpenAPI document.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenApiDocument"
                }
              }
            }
          }
        }
      }
    },
    "/endpoints/{endpointPath}": {
      "parameters": [
        {
          "name": "endpointPath",
          "in": "path",
          "required": true,
          "description": "The path of a scripted endpoint as declared in the template, with its parameters filled in (`orders/42` for `orders/:id`). A multi-segment path needs its `/` sent unencoded, which OpenAPI path templating does not do: for those, use the per-endpoint operations of `getOpenApiDocument`.",
          "schema": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_.~%-]+(/[A-Za-z0-9_.~%-]+)*$"
          },
          "example": "orders-summary"
        },
        {
          "$ref": "#/components/parameters/VGuard"
        }
      ],
      "get": {
        "operationId": "getScriptedEndpoint",
        "tags": [
          "Scripted endpoints"
        ],
        "summary": "Call a scripted GET endpoint",
        "description": "Runs the project script the template binds to this `GET` route and returns its value as JSON. Which endpoints exist depends on the template: `getOpenApiDocument` lists them. The query string reaches the script as `request.query` (a repeated key as an array); the API key never does. Part of a paid plan that dcupl turns on for a project. Answers are cacheable for an hour (`cache-control: private, max-age=3600`; `public` on an open instance; `no-store` on errors).",
        "externalDocs": {
          "url": "https://docs.dcupl.com/console/rapi/scripted-endpoints",
          "description": "Scripted endpoints"
        },
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": false,
            "description": "The query parameters the script reads, as name/value pairs (`?customer=acme`).",
            "style": "form",
            "explode": true,
            "schema": {
              "type": "object",
              "additionalProperties": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                ]
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The script's return value.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EndpointResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "No endpoint matches method and path (\"endpoint not found\").",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "statusCode": 404,
                  "message": "endpoint not found",
                  "error": "Not Found"
                }
              }
            }
          },
          "500": {
            "description": "The script threw.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScriptError"
                }
              }
            }
          },
          "504": {
            "description": "The script did not settle within its time budget (5000 ms on a dcupl-hosted runner).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScriptError"
                },
                "example": {
                  "name": "EndpointTimeout",
                  "message": "endpoint script did not settle within 5000ms"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "postScriptedEndpoint",
        "tags": [
          "Scripted endpoints"
        ],
        "summary": "Call a scripted POST endpoint",
        "description": "Runs the project script the template binds to this `POST` route with the JSON body as `request.body` and returns its value as JSON (status 200). A `GET` entry of the same path does not answer a `POST`. Part of a paid plan that dcupl turns on for a project. Answers are cacheable for an hour (`cache-control: private, max-age=3600`; `public` on an open instance; `no-store` on errors).",
        "externalDocs": {
          "url": "https://docs.dcupl.com/console/rapi/scripted-endpoints",
          "description": "Scripted endpoints"
        },
        "requestBody": {
          "required": false,
          "description": "Any JSON the script reads as `request.body`; other content types are refused with 415.",
          "content": {
            "application/json": {
              "schema": {
                "description": "Free-form JSON."
              },
              "example": {
                "customers": [
                  "acme",
                  "globex"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The script's return value.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EndpointResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "No endpoint matches method and path (\"endpoint not found\").",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "statusCode": 404,
                  "message": "endpoint not found",
                  "error": "Not Found"
                }
              }
            }
          },
          "415": {
            "description": "The body is not JSON (\"endpoint bodies must be application/json\").",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The script threw.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScriptError"
                }
              }
            }
          },
          "504": {
            "description": "The script did not settle within its time budget (5000 ms on a dcupl-hosted runner).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScriptError"
                }
              }
            }
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "operationId": "postMcp",
        "tags": [
          "MCP"
        ],
        "summary": "Model Context Protocol endpoint",
        "description": "A stateless Streamable HTTP MCP server over the instance: every JSON-RPC `POST` is self-sufficient, with no sessions and no server-sent events (`GET` and `DELETE` answer 405). Send `Accept: application/json, text/event-stream`. Connect an MCP client (Claude Code, Cursor, VS Code, the MCP Inspector) to this URL with the `api-key` header instead of calling it by hand. Read-only tools: `models`, `guide`, `query`, `facet`, `suggest`, `aggregate`, `pivot`, `metadata`, plus one `endpoint_<method>_<path>` tool per scripted endpoint; one resource, `dcupl://instance/{instanceKey}/guide`. Served only where the template turns MCP on (part of a paid plan that dcupl turns on for a project); otherwise 404. Server card: https://dcupl.com/.well-known/mcp/server-card.json.",
        "externalDocs": {
          "url": "https://docs.dcupl.com/console/rapi/mcp",
          "description": "MCP endpoint"
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/VGuard"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              },
              "example": {
                "jsonrpc": "2.0",
                "id": 1,
                "method": "tools/list"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The JSON-RPC answer (also for JSON-RPC errors and failed tool calls).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "The deployed template does not turn MCP on.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "406": {
            "description": "The `Accept` header does not list both `application/json` and `text/event-stream`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "api-key": {
        "type": "apiKey",
        "in": "header",
        "name": "api-key",
        "description": "The API key of the instance’s template. Only the header name `api-key` is accepted."
      },
      "api-key-query": {
        "type": "apiKey",
        "in": "query",
        "name": "api-key",
        "description": "The same key as a query parameter (also spelled `apiKey`); prefer the header."
      }
    },
    "parameters": {
      "VGuard": {
        "name": "v",
        "in": "query",
        "required": false,
        "description": "v-Guard: the current `v` from `getStatus`. Required on every data request when the instance has v-Guard turned on (also accepted as the `v` header); a missing or outdated value is answered with `400 Invalid v parameter` — read `v` again and retry. Ignored when v-Guard is off.",
        "schema": {
          "type": "string"
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The options are invalid or unparsable, the instance is not `ready` (\"instance not ready\"), or v-Guard is on and `v` is missing or outdated (\"Invalid v parameter\").",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "statusCode": 400,
              "message": "instance not ready",
              "error": "Bad Request"
            }
          }
        }
      },
      "Forbidden": {
        "description": "No or a wrong API key, or an unknown instance key (\"Forbidden resource\").",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "statusCode": 403,
              "message": "Forbidden resource",
              "error": "Forbidden"
            }
          }
        }
      }
    },
    "schemas": {
      "DcuplQuery": {
        "type": "object",
        "description": "One filter condition: `{ attribute, operator, value, options? }`.",
        "required": [
          "attribute",
          "operator"
        ],
        "properties": {
          "attribute": {
            "type": "string",
            "minLength": 1,
            "description": "Attribute to filter on; a dotted path follows references, e.g. `vendor.country`."
          },
          "operator": {
            "type": "string",
            "minLength": 1,
            "description": "Built-in operators: `eq` (whole value equals), `in` (value is an array; equals any entry), `find` (plain string = exact whole value, case-sensitive; \"/…/\" = JavaScript regex matched anywhere, flags in options.regexFlags; object = property match), `gt`, `gte`, `lt`, `lte` (numbers; epoch milliseconds for dates), `typeof` (JavaScript type name), `isTruthy` (true = non-empty; false = null, missing, \"\" or 0), `size` (array or string length). A custom operator registered on the instance is accepted by its name; any other name is rejected.",
            "examples": [
              "eq",
              "in",
              "find",
              "gte"
            ]
          },
          "value": {
            "description": "Shape per operator: an array for `in`, a string or \"/…/\" regex for `find`, a number for `gt`/`gte`/`lt`/`lte`/`size`, a boolean for `isTruthy`. Item keys are strings: filter with \"42\", not 42."
          },
          "queryKey": {
            "type": "string",
            "description": "Optional key identifying this condition."
          },
          "options": {
            "type": "object",
            "description": "Modifiers of this condition.",
            "properties": {
              "invert": {
                "type": "boolean",
                "description": "Negate the condition (NOT); works for every built-in operator."
              },
              "transform": {
                "type": "array",
                "description": "Normalise the attribute value and the value before comparing, applied in order.",
                "items": {
                  "type": "string",
                  "enum": [
                    "lowercase",
                    "trim",
                    "removeWhitespace"
                  ]
                }
              },
              "arrayValueHandling": {
                "type": "string",
                "enum": [
                  "some",
                  "every"
                ],
                "description": "For list attributes: match if some (default) or every entry matches."
              },
              "regexFlags": {
                "type": "string",
                "description": "JavaScript regex flags for a `find` \"/…/\" value, e.g. \"i\" = case-insensitive."
              }
            },
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "DcuplQueryGroup": {
        "type": "object",
        "description": "Conditions or nested groups combined with `groupType`.",
        "required": [
          "queries"
        ],
        "properties": {
          "groupType": {
            "$ref": "#/components/schemas/GroupType"
          },
          "groupKey": {
            "type": "string",
            "description": "Optional key identifying this group."
          },
          "queries": {
            "$ref": "#/components/schemas/DcuplQueryList"
          }
        },
        "additionalProperties": true
      },
      "DcuplQueryList": {
        "type": "array",
        "description": "Conditions (`{ attribute, operator, value }`) or nested groups (`{ groupType, queries }`).",
        "items": {
          "anyOf": [
            {
              "$ref": "#/components/schemas/DcuplQuery"
            },
            {
              "$ref": "#/components/schemas/DcuplQueryGroup"
            }
          ]
        }
      },
      "GroupType": {
        "type": "string",
        "enum": [
          "and",
          "or"
        ],
        "default": "and",
        "description": "How the conditions combine: `and` = every entry must match (default); `or` = at least one."
      },
      "Projection": {
        "type": "object",
        "description": "Attributes to return: `{ \"name\": true }` = key + name; `{ \"$\": true }` = every attribute; `\"x\": false` drops x; a nested object projects a referenced model, e.g. `{ \"vendor\": { \"name\": true } }`.",
        "properties": {
          "$": {
            "type": "boolean",
            "description": "Return every attribute of the model."
          },
          "$$": {
            "type": "boolean",
            "description": "Return every attribute, references resolved one level deep."
          }
        },
        "additionalProperties": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "$ref": "#/components/schemas/Projection"
            }
          ]
        }
      },
      "Sort": {
        "type": "object",
        "description": "Sort order: `{ \"attributes\": [\"price\"], \"order\": [\"DESC\"] }` (one direction per attribute, upper case) or `{ \"script\": { \"key\": \"…\" } }` for a registered sort script.",
        "properties": {
          "attributes": {
            "type": "array",
            "description": "Attributes to sort by, in priority order.",
            "items": {
              "type": "string",
              "minLength": 1
            }
          },
          "order": {
            "type": "array",
            "description": "One direction per attribute, upper case only.",
            "items": {
              "type": "string",
              "enum": [
                "ASC",
                "DESC"
              ]
            }
          },
          "script": {
            "type": "object",
            "description": "Sort with a registered sort script instead of attributes/order.",
            "required": [
              "key"
            ],
            "properties": {
              "key": {
                "type": "string",
                "description": "Key of the registered sort script."
              },
              "options": {
                "description": "Options passed to the sort script."
              }
            },
            "additionalProperties": true
          }
        },
        "additionalProperties": false
      },
      "QueryOptions": {
        "type": "object",
        "description": "A query against one model: filter conditions, paging, projection and sort. There are no routes per model: name the model in `modelKey` (`getOverview` lists them).",
        "required": [
          "modelKey"
        ],
        "properties": {
          "modelKey": {
            "type": "string",
            "minLength": 1,
            "description": "Key of the model to query."
          },
          "queries": {
            "$ref": "#/components/schemas/DcuplQueryList",
            "description": "Conditions or groups; an empty list (default) matches every item.",
            "default": []
          },
          "groupType": {
            "$ref": "#/components/schemas/GroupType"
          },
          "groupKey": {
            "type": "string",
            "description": "Optional key identifying the root group."
          },
          "start": {
            "type": "integer",
            "minimum": 0,
            "description": "Paging: zero-based offset of the first item; start 20 + count 10 = items 21–30."
          },
          "count": {
            "type": "integer",
            "minimum": 0,
            "description": "Paging: maximum number of items to return. Set it on large models; for totals use `postAggregate` or `postMetadata` instead of paging through a model."
          },
          "projection": {
            "$ref": "#/components/schemas/Projection"
          },
          "sort": {
            "$ref": "#/components/schemas/Sort"
          }
        },
        "additionalProperties": true
      },
      "FacetRequest": {
        "type": "object",
        "description": "Facet options: the distinct values of one attribute with their item counts.",
        "required": [
          "modelKey",
          "options"
        ],
        "properties": {
          "modelKey": {
            "type": "string",
            "minLength": 1,
            "description": "Key of the model."
          },
          "options": {
            "type": "object",
            "required": [
              "attribute"
            ],
            "properties": {
              "attribute": {
                "type": "string",
                "minLength": 1,
                "description": "Attribute to count the values of."
              },
              "count": {
                "type": "integer",
                "minimum": 0,
                "description": "Maximum number of facet entries to return."
              },
              "sort": {
                "type": "string",
                "enum": [
                  "size-desc",
                  "size-asc",
                  "value-asc",
                  "value-desc"
                ],
                "description": "Entry order by item count or by value; omitted = index order."
              },
              "excludeZeros": {
                "type": "boolean",
                "description": "Leave out entries with no matching items."
              },
              "excludeUndefineds": {
                "type": "boolean",
                "description": "Leave out the entry for undefined values."
              },
              "excludeUnresolved": {
                "type": "boolean",
                "description": "Leave out references that do not resolve."
              },
              "calculateResults": {
                "type": "boolean",
                "description": "Include the matching item keys per entry."
              },
              "excludeGroup": {
                "type": "string",
                "description": "`groupKey` of the query group left out when counting; defaults to the attribute."
              }
            },
            "additionalProperties": true,
            "description": "Which attribute to facet and how."
          },
          "query": {
            "$ref": "#/components/schemas/QueryOptions",
            "description": "Optional filter applied first, in the shape of the query options."
          }
        },
        "additionalProperties": true
      },
      "AggregationOptions": {
        "type": "object",
        "description": "Aggregations over one attribute.",
        "required": [
          "attribute",
          "types"
        ],
        "properties": {
          "attribute": {
            "type": "string",
            "minLength": 1,
            "description": "Attribute to aggregate; a dotted path is allowed."
          },
          "types": {
            "type": "array",
            "minItems": 1,
            "description": "Aggregations to compute; `sum` and `avg` need a numeric attribute.",
            "items": {
              "type": "string",
              "enum": [
                "sum",
                "avg",
                "count",
                "min",
                "max",
                "distinct",
                "group"
              ]
            }
          },
          "distinctOptions": {
            "type": "object",
            "description": "Options of the `distinct` aggregation.",
            "properties": {
              "limit": {
                "type": "integer",
                "minimum": 0,
                "description": "Maximum number of distinct values."
              },
              "skipKeys": {
                "type": "boolean",
                "description": "Leave out the item keys per distinct value."
              }
            },
            "additionalProperties": true
          },
          "groupOptions": {
            "type": "object",
            "description": "Options of the `group` aggregation.",
            "properties": {
              "calculateNotFound": {
                "type": "boolean",
                "description": "Also count the items that fall into no group."
              },
              "groups": {
                "type": "array",
                "description": "Groups to count items into: a range (`from`, `to`) or a list of values (`value`).",
                "items": {
                  "$ref": "#/components/schemas/AggregationGroupOption"
                }
              }
            },
            "additionalProperties": true
          },
          "excludeUndefineds": {
            "type": "boolean",
            "description": "Leave the undefined value out of `distinct`."
          }
        },
        "additionalProperties": true
      },
      "AggregationGroupOption": {
        "type": "object",
        "description": "One group of the `group` aggregation.",
        "properties": {
          "from": {
            "description": "Lower bound of a range group."
          },
          "to": {
            "description": "Upper bound of a range group."
          },
          "value": {
            "type": "array",
            "items": {},
            "description": "Values of a value group."
          }
        },
        "additionalProperties": true
      },
      "AggregateRequest": {
        "type": "object",
        "description": "Aggregate options: statistics over one attribute, optionally filtered first.",
        "required": [
          "modelKey",
          "options"
        ],
        "properties": {
          "modelKey": {
            "type": "string",
            "minLength": 1,
            "description": "Key of the model."
          },
          "options": {
            "$ref": "#/components/schemas/AggregationOptions"
          },
          "query": {
            "$ref": "#/components/schemas/QueryOptions",
            "description": "Optional filter applied first, in the shape of the query options."
          }
        },
        "additionalProperties": true
      },
      "PivotDimension": {
        "type": "object",
        "description": "A row or column dimension.",
        "required": [
          "attribute"
        ],
        "properties": {
          "attribute": {
            "type": "string",
            "minLength": 1,
            "description": "Attribute whose values form this dimension."
          },
          "calculateTotals": {
            "type": "boolean",
            "description": "Compute totals for this dimension."
          }
        },
        "additionalProperties": true
      },
      "PivotRequest": {
        "type": "object",
        "description": "Pivot options: row and column dimensions with aggregations per cell, optionally filtered first.",
        "required": [
          "modelKey",
          "options"
        ],
        "properties": {
          "modelKey": {
            "type": "string",
            "minLength": 1,
            "description": "Key of the model."
          },
          "options": {
            "type": "object",
            "description": "The pivot table to compute.",
            "required": [
              "rows",
              "columns",
              "values"
            ],
            "properties": {
              "rows": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PivotDimension"
                },
                "description": "Row dimensions, outermost first."
              },
              "columns": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PivotDimension"
                },
                "description": "Column dimensions, outermost first."
              },
              "values": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AggregationOptions"
                },
                "description": "Aggregations computed per cell, e.g. `[{ \"attribute\": \"price\", \"types\": [\"sum\"] }]`."
              },
              "options": {
                "type": "object",
                "description": "Pivot-wide options.",
                "properties": {
                  "calculateTotals": {
                    "type": "boolean",
                    "description": "Compute the totals (default true)."
                  }
                },
                "additionalProperties": true
              }
            },
            "additionalProperties": true
          },
          "query": {
            "$ref": "#/components/schemas/QueryOptions",
            "description": "Optional filter applied first, in the shape of the query options."
          }
        },
        "additionalProperties": true
      },
      "SuggestRequest": {
        "type": "object",
        "description": "Suggest options: stored values of an attribute that match a partial input (autocomplete).",
        "required": [
          "modelKey",
          "options"
        ],
        "properties": {
          "modelKey": {
            "type": "string",
            "minLength": 1,
            "description": "Key of the model."
          },
          "options": {
            "type": "object",
            "description": "What to complete and how.",
            "required": [
              "attribute",
              "value"
            ],
            "properties": {
              "attribute": {
                "type": "string",
                "minLength": 1,
                "description": "Attribute to suggest values of."
              },
              "value": {
                "type": "string",
                "description": "A plain value is a case-insensitive prefix (\"bask\" completes to \"Basketball\", \"ball\" does not); \"/…/\" is a regex, case-sensitive unless `regexFlags` is \"i\"."
              },
              "max": {
                "type": "integer",
                "minimum": 0,
                "description": "Maximum number of suggestions (default 20)."
              },
              "regexFlags": {
                "type": "string",
                "description": "JavaScript regex flags for a \"/…/\" value, e.g. \"i\"."
              },
              "calculateResultKeys": {
                "type": "boolean",
                "description": "Include the matching item keys per suggestion."
              },
              "excludeUndefineds": {
                "type": "boolean",
                "description": "Leave out undefined values."
              },
              "excludeNulls": {
                "type": "boolean",
                "description": "Leave out null values."
              },
              "transform": {
                "type": "array",
                "description": "Normalise values before matching, applied in order.",
                "items": {
                  "type": "string",
                  "enum": [
                    "lowercase",
                    "trim",
                    "removeWhitespace"
                  ]
                }
              },
              "relevantData": {
                "type": "string",
                "enum": [
                  "filtered",
                  "all",
                  "excludeQuery"
                ],
                "description": "Items to suggest from: `filtered` (by `query`, default), `all`, or `excludeQuery` (the items of `query` without the condition or group in `excludeQuery`, which is then required)."
              },
              "excludeQuery": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/DcuplQuery"
                  },
                  {
                    "$ref": "#/components/schemas/DcuplQueryGroup"
                  }
                ],
                "description": "Condition or group removed from `query` before suggesting; only with `excludeQuery`."
              }
            },
            "additionalProperties": true
          },
          "query": {
            "$ref": "#/components/schemas/QueryOptions",
            "description": "Optional filter applied first, in the shape of the query options."
          }
        },
        "additionalProperties": true
      },
      "MetadataRequest": {
        "type": "object",
        "description": "Metadata options: a model, optionally filtered.",
        "required": [
          "modelKey"
        ],
        "properties": {
          "modelKey": {
            "type": "string",
            "minLength": 1,
            "description": "Key of the model."
          },
          "query": {
            "$ref": "#/components/schemas/QueryOptions",
            "description": "Optional filter; `currentSize` in the answer counts its matches."
          }
        },
        "additionalProperties": true
      },
      "Item": {
        "type": "object",
        "description": "One item of a model: its string `key` plus the projected attributes. A reference comes back as `{ key }`.",
        "required": [
          "key"
        ],
        "properties": {
          "key": {
            "type": "string",
            "description": "The item key, always a string."
          }
        },
        "additionalProperties": true
      },
      "QueryResult": {
        "type": "array",
        "description": "The matching items, in sort order.",
        "items": {
          "$ref": "#/components/schemas/Item"
        }
      },
      "FacetEntry": {
        "type": "object",
        "description": "One value of the faceted attribute.",
        "required": [
          "key",
          "size"
        ],
        "properties": {
          "key": {
            "type": "string",
            "description": "The entry key (the value as a string)."
          },
          "value": {
            "type": [
              "string",
              "boolean",
              "null"
            ],
            "description": "The attribute value; null or missing for the undefined entry."
          },
          "size": {
            "type": "integer",
            "description": "Number of matching items with this value."
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether the entry has matching items."
          },
          "selected": {
            "type": "boolean",
            "description": "Whether the query already filters on this value."
          },
          "resultKeys": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Keys of the matching items (with `calculateResults`)."
          },
          "entry": {
            "type": "object",
            "additionalProperties": true,
            "description": "The referenced item, for a reference."
          },
          "children": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FacetEntry"
            },
            "description": "Nested entries, where the facet has levels."
          }
        },
        "additionalProperties": true
      },
      "FacetResult": {
        "type": "array",
        "description": "One entry per value of the attribute.",
        "items": {
          "$ref": "#/components/schemas/FacetEntry"
        }
      },
      "Aggregation": {
        "type": "object",
        "description": "The requested aggregations over one attribute; only the requested types are set.",
        "required": [
          "attribute",
          "types"
        ],
        "properties": {
          "attribute": {
            "type": "string",
            "description": "The aggregated attribute."
          },
          "types": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The requested aggregation types."
          },
          "sum": {
            "type": "number",
            "description": "Sum of the values."
          },
          "avg": {
            "type": "number",
            "description": "Average of the values."
          },
          "count": {
            "type": "integer",
            "description": "Number of items with a value."
          },
          "min": {
            "type": "number",
            "description": "Smallest value."
          },
          "max": {
            "type": "number",
            "description": "Largest value."
          },
          "distinct": {
            "type": "array",
            "description": "The distinct values with their counts.",
            "items": {
              "type": "object",
              "required": [
                "value",
                "count"
              ],
              "properties": {
                "value": {
                  "type": "string",
                  "description": "The value."
                },
                "count": {
                  "type": "integer",
                  "description": "Number of items with this value."
                },
                "keys": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "Their item keys (unless skipKeys)."
                }
              },
              "additionalProperties": true
            }
          },
          "group": {
            "type": "array",
            "description": "One entry per requested group.",
            "items": {
              "type": "object",
              "required": [
                "option",
                "count"
              ],
              "properties": {
                "option": {
                  "$ref": "#/components/schemas/AggregationGroupOption"
                },
                "count": {
                  "type": "integer",
                  "description": "Number of items in the group."
                },
                "keys": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "Their item keys."
                }
              },
              "additionalProperties": true
            }
          }
        },
        "additionalProperties": true
      },
      "PivotResult": {
        "type": "object",
        "description": "A tree of dimension items and cells. The root (`key: \"root\"`) holds the first row dimension in `rows`, the first column dimension in `columns` and the totals in `values`; a cell has `key`/`value` = one value of its dimension and `values` = one aggregation per requested value.",
        "required": [
          "key"
        ],
        "properties": {
          "key": {
            "type": "string",
            "description": "\"root\", a dimension attribute, or a cell value."
          },
          "value": {
            "description": "The dimension value of a cell."
          },
          "values": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Aggregation"
            },
            "description": "Aggregations over the cell items."
          },
          "rows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PivotResult"
            },
            "description": "Row dimension items or cells."
          },
          "columns": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PivotResult"
            },
            "description": "Column dimension items or cells."
          }
        },
        "additionalProperties": true
      },
      "Suggestion": {
        "type": "object",
        "description": "One stored value that matches the input.",
        "required": [
          "value"
        ],
        "properties": {
          "value": {
            "type": "string",
            "description": "The stored value, exactly as it is filtered on."
          },
          "keys": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Keys of the items with this value."
          }
        },
        "additionalProperties": true
      },
      "SuggestResult": {
        "type": "array",
        "description": "The matching values.",
        "items": {
          "$ref": "#/components/schemas/Suggestion"
        }
      },
      "ModelMetadata": {
        "type": "object",
        "description": "A model's item counts and its attributes.",
        "required": [
          "key",
          "currentSize",
          "initialSize"
        ],
        "properties": {
          "key": {
            "type": "string",
            "description": "The model key."
          },
          "currentSize": {
            "type": "integer",
            "description": "Number of items matching the query."
          },
          "initialSize": {
            "type": "integer",
            "description": "Total number of items of the model."
          },
          "appliedQuery": {
            "type": "object",
            "additionalProperties": true,
            "description": "The query that was applied."
          },
          "attributes": {
            "type": "array",
            "description": "The attributes of the model (properties and references) with their types.",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "views": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            },
            "description": "The model views."
          }
        },
        "additionalProperties": true
      },
      "InstanceStatus": {
        "type": "object",
        "description": "What the instance loaded, its version hash `v` and, while `status` is `error`, why it failed.",
        "required": [
          "key",
          "status"
        ],
        "properties": {
          "key": {
            "type": "string",
            "description": "The instance key."
          },
          "uid": {
            "type": "string",
            "description": "Unique id of this deployment."
          },
          "status": {
            "type": "string",
            "enum": [
              "waiting",
              "processing",
              "ready",
              "updating",
              "error",
              "stopped"
            ],
            "description": "`ready` and `updating` answer data requests (`updating` from the previous data); the others answer `400 instance not ready`."
          },
          "v": {
            "type": "string",
            "description": "Version hash of the deployed configuration, checked by v-Guard."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the instance was created."
          },
          "changedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When its configuration last changed."
          },
          "instanceChangedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When its status last changed."
          },
          "templateVersion": {
            "type": "string",
            "description": "Version of the deployed API template, if set."
          },
          "runnerInstanceId": {
            "type": "string",
            "description": "Id of the runner process serving the instance."
          },
          "report": {
            "type": "object",
            "description": "What the last start loaded.",
            "properties": {
              "resources": {
                "type": "object",
                "description": "Resources scheduled and skipped (with the reason), unresolved loader variables.",
                "additionalProperties": true
              },
              "quality": {
                "type": "object",
                "description": "Number of quality errors and the first 20 of them.",
                "additionalProperties": true
              },
              "models": {
                "type": "integer",
                "description": "Number of models loaded."
              },
              "items": {
                "type": "integer",
                "description": "Number of items loaded."
              },
              "durationMs": {
                "type": "number",
                "description": "Duration of the start in milliseconds."
              }
            },
            "additionalProperties": true
          },
          "error": {
            "type": "object",
            "description": "Why the start failed (status `error`).",
            "properties": {
              "message": {
                "type": "string",
                "description": "The error message."
              },
              "name": {
                "type": "string",
                "description": "The error name."
              },
              "phase": {
                "type": "string",
                "enum": [
                  "fetch-config",
                  "process",
                  "init",
                  "worker"
                ],
                "description": "The phase that failed."
              },
              "at": {
                "type": "string",
                "format": "date-time",
                "description": "When it failed."
              }
            },
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "InstanceDetails": {
        "description": "The status plus memory figures and the call counters.",
        "allOf": [
          {
            "$ref": "#/components/schemas/InstanceStatus"
          },
          {
            "type": "object",
            "properties": {
              "runtime": {
                "type": "object",
                "description": "Heap figures in megabytes; both 0 while the instance cannot answer.",
                "properties": {
                  "used_heap_size": {
                    "type": "number",
                    "description": "Used heap in MB."
                  },
                  "max_heap_size": {
                    "type": "number",
                    "description": "Heap limit in MB."
                  }
                },
                "additionalProperties": true
              },
              "invocations": {
                "$ref": "#/components/schemas/Invocations"
              }
            }
          }
        ]
      },
      "Overview": {
        "type": "object",
        "description": "The models of the loaded application with their item counts.",
        "required": [
          "models"
        ],
        "properties": {
          "models": {
            "type": "array",
            "description": "One entry per model.",
            "items": {
              "type": "object",
              "required": [
                "key",
                "count"
              ],
              "properties": {
                "key": {
                  "type": "string",
                  "description": "The model key, the `modelKey` of every query route."
                },
                "count": {
                  "type": "integer",
                  "description": "Number of items."
                }
              },
              "additionalProperties": true
            }
          }
        },
        "additionalProperties": true
      },
      "InvocationCounter": {
        "type": "object",
        "description": "Calls of one action since the runner started.",
        "properties": {
          "completed": {
            "type": "integer",
            "description": "Calls that completed."
          },
          "failed": {
            "type": "integer",
            "description": "Calls that failed."
          }
        },
        "additionalProperties": true
      },
      "Invocations": {
        "description": "Call counters, each with `completed` and `failed`: one for the instance and one per action — the query routes by name (`query`, `facet`, …), `endpoint` and `endpoint:<path>` for scripted endpoints, `mcp:<tool>` for MCP calls. They live in memory and restart from zero with the runner.",
        "type": [
          "object",
          "array"
        ],
        "additionalProperties": true,
        "items": {
          "$ref": "#/components/schemas/InvocationCounter"
        }
      },
      "OpenApiDocument": {
        "type": "object",
        "description": "An OpenAPI 3.0 document.",
        "required": [
          "openapi",
          "info",
          "paths"
        ],
        "properties": {
          "openapi": {
            "type": "string",
            "description": "The OpenAPI version."
          },
          "info": {
            "type": "object",
            "additionalProperties": true,
            "description": "Title, description and version."
          },
          "paths": {
            "type": "object",
            "additionalProperties": true,
            "description": "The routes of the instance."
          }
        },
        "additionalProperties": true
      },
      "EndpointResult": {
        "description": "The script's return value as JSON (`undefined` becomes `null`); its shape is the script's own."
      },
      "JsonRpcRequest": {
        "type": "object",
        "description": "One JSON-RPC 2.0 message of the Model Context Protocol, e.g. `initialize`, `tools/list`, `tools/call`, `resources/list`, `resources/read`. Batches (arrays) are not supported.",
        "required": [
          "jsonrpc",
          "method"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0",
            "description": "Always \"2.0\"."
          },
          "id": {
            "type": [
              "string",
              "integer"
            ],
            "description": "Request id; omitted for a notification."
          },
          "method": {
            "type": "string",
            "description": "The MCP method.",
            "examples": [
              "initialize",
              "tools/list",
              "tools/call"
            ]
          },
          "params": {
            "type": "object",
            "additionalProperties": true,
            "description": "The method parameters."
          }
        },
        "additionalProperties": true
      },
      "JsonRpcResponse": {
        "type": "object",
        "description": "The JSON-RPC 2.0 answer: `result` on success, `error` otherwise (`-32002` = instance not ready, `-32600` = batch sent). A failed tool call is a `result` with `isError: true` and the reason in its text.",
        "required": [
          "jsonrpc"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0",
            "description": "Always \"2.0\"."
          },
          "id": {
            "type": [
              "string",
              "integer",
              "null"
            ],
            "description": "The id of the request."
          },
          "result": {
            "type": "object",
            "additionalProperties": true,
            "description": "The method result."
          },
          "error": {
            "type": "object",
            "description": "The JSON-RPC error.",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "integer",
                "description": "The error code."
              },
              "message": {
                "type": "string",
                "description": "The error message."
              },
              "data": {
                "description": "Additional error data."
              }
            },
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "Error": {
        "type": "object",
        "description": "The error answer of the runner, e.g. `{ \"statusCode\": 403, \"message\": \"Forbidden resource\", \"error\": \"Forbidden\" }`.",
        "required": [
          "statusCode",
          "message"
        ],
        "properties": {
          "statusCode": {
            "type": "integer",
            "description": "The HTTP status code."
          },
          "message": {
            "description": "What went wrong, e.g. \"instance not ready\", \"Invalid v parameter\", \"endpoint not found\".",
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            ]
          },
          "error": {
            "type": "string",
            "description": "The HTTP status text, e.g. \"Bad Request\"."
          }
        },
        "additionalProperties": true
      },
      "ScriptError": {
        "type": "object",
        "description": "A scripted endpoint that threw or timed out; never a stack.",
        "required": [
          "name",
          "message"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "The error name, e.g. \"TypeError\" or \"EndpointTimeout\"."
          },
          "message": {
            "type": "string",
            "description": "The error message."
          }
        },
        "additionalProperties": true
      }
    }
  }
}
