apidocs

var SwaggerInfo = &swag.Spec{
	Version:          "1.0",
	Host:             "localhost:8080",
	BasePath:         "/api/v1",
	Schemes:          []string{},
	Title:            "MCP Data Platform API",
	Description:      "The platform's REST surface: the admin API, the portal API, and the gateway\nroutes a non-MCP client calls an upstream connection through.\n\nEvery route below authenticates. Almost every one answers JSON; the handful\nthat return a file, an image, a page or YAML say so in their `produces`.\n\n# Getting started\n\nThe base URL is the origin you fetched this document from, followed by\n`/api/v1`. The `host` at the top of this reference is that origin: the\ndocument is rewritten as it is served, so the URLs here are the ones this\ndeployment answers on.\n\nThe first call to make is the one that tells you who the platform thinks you\nare:\n\n```\ncurl -H \"X-API-Key: $MCP_API_KEY\" https://$HOST/api/v1/portal/me\n```\n\nwhich answers:\n\n```json\n{\n  \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"email\": \"analyst@example.com\",\n  \"roles\": [\"analyst\", \"data_engineer\"],\n  \"persona\": \"analyst\",\n  \"is_admin\": false,\n  \"tools\": [\"trino_query\", \"datahub_search\"]\n}\n```\n\n`persona` is the one field to read first. A persona decides which tools and\nwhich connections this credential reaches, so a 403 further down this reference\nis usually answered here rather than at the route that returned it.\n\n# Authentication\n\nEvery route accepts either credential, in either of two headers. A request with\nneither is refused with 401.\n\n## API key\n\n```\nX-API-Key: <key>\n```\n\nAn administrator issues one in the portal under Admin > Keys\n(`/portal/admin/keys`), choosing the roles it carries. The key value is\nreturned once, at creation, and never again by any route: the list of keys\nshows names and roles only. Keys declared in the deployment's configuration\nfile are read-only and cannot be revoked through the API.\n\nHold an API key when the caller is a script, a scheduled job, or an\nintegration with no person behind it.\n\n## OIDC bearer token\n\n```\nAuthorization: Bearer <jwt>\n```\n\nA JWT, validated against the deployment's identity provider. Either an access\ntoken from the OIDC provider the portal signs in against, or one the\nplatform's own OAuth 2.1 authorization server issued to an MCP client.\n\nHold a bearer token when the call acts as a person, so that the roles, the\npersona and the audit trail are that person's.\n\n# Calling a connection through the gateway\n\nAn upstream API registered as a connection is reachable over REST without an\nMCP client. This is what NiFi, Airflow, a cron job or curl come to this\nreference for.\n\n```\nPOST /api/v1/gateway/{connection}/invoke\n```\n\n`{connection}` is the connection's name, exactly as `GET /api/v1/apis` lists\nit. That route answers with the connections this credential reaches, and\n`/apis/{connection}/operations` with what each one offers, so a caller finds\nits own targets without holding an administrator's credential. The body says\nwhat to call on that upstream:\n\n```json\n{\n  \"method\": \"GET\",\n  \"path\": \"/customers\",\n  \"query_params\": {\"limit\": 50}\n}\n```\n\nThe gateway holds the upstream's credentials, so the request above carries only\nthe platform's own. The reply is an envelope: the upstream's status code is\n`status` inside the body, not on the HTTP status line. See the Gateway section\nfor what each platform-level status means and for `paginate`, which makes one\ncall walk every page.\n\n`/invoke-raw` is the same call with the upstream's body streamed back\nunbuffered, for a large or binary response. That route does put the upstream's\nstatus on the HTTP status line, because the response is committed before the\nstatus is known.\n\nTo browse the same catalog and copy a ready-made call, open `/portal/apis` in\nthe portal.\n\n# Conventions\n\n## Paging and filtering\n\nA list route pages one of two ways, and each operation's parameters say which.\nMost take `limit` and `offset`. The admin list routes take `per_page` and a\n1-based `page` instead; there, a page below 1 or a value that is not a number\nreads as the first page. Routes that filter by time take RFC3339 timestamps,\nand a timestamp that cannot be parsed widens the query rather than failing it.\n\n## Errors\n\nMost routes report an error as an RFC 9457 problem document, sent as\n`application/problem+json`:\n\n```json\n{\n  \"type\": \"about:blank\",\n  \"title\": \"Not Found\",\n  \"status\": 404,\n  \"detail\": \"resource not found\"\n}\n```\n\n`type` is `about:blank` unless the platform has a name for the problem, in\nwhich case it is a `urn:mcp-data-platform:problem:` URN that a client can\ncompare against. `detail` is prose for a person.\n\nThe gateway data plane and the managed-resource routes answer with a single\n`error` string instead, because that is the shape their MCP counterparts\nalready return and a client of both should not have to read two:\n\n```json\n{\"error\": \"connection \\\"acme-billing\\\" is not registered\"}\n```\n\nEach operation's responses name the body it sends, so the one to expect is\nalways on the page.\n\n## Whose status code it is\n\nOn every route except the gateway's, the HTTP status is the platform's own\nanswer.\n\nOn `POST /gateway/{connection}/invoke` it is still the platform's own answer,\nand the upstream's is `status` inside the body. A 404 from the upstream arrives\nas HTTP 200 with `\"status\": 404`. That split is deliberate: it lets a client\nroute on \"the gateway is broken\" (502, 504) separately from \"the upstream is\nunhappy\".\n\n## Which replica answered\n\nEvery response carries `X-Platform-Instance`, naming the process that served\nit. A deployment behind a load balancer runs more than one, and that header is\nwhat makes a reply attributable to one of them.\n\n# The MCP surface is elsewhere\n\nThis document describes the REST API only. The Model Context Protocol surface\nthat AI clients connect to, and the tools it registers, are not in here: MCP is\nserved over streamable HTTP at the deployment's root, with the legacy SSE\ntransport at `/sse`. A client that speaks MCP discovers the tools by connecting\nand calling `tools/list`, not by reading this reference.",
	InfoInstanceName: "swagger",
	SwaggerTemplate:  docTemplate,
	LeftDelim:        "{{",
	RightDelim:       "}}",
}