{ "openapi": "3.1.0", "info": { "title": "Topline External API", "version": "1.0.0", "description": "Supported OAuth, Harness MCP, artifact-app, and Developer Access endpoints. Compatibility policy: https://topline.build/docs/api-lifecycle" }, "servers": [ { "url": "https://topline.build" } ], "paths": { "/api/docs": { "get": { "operationId": "get_api_docs", "tags": [ "Documentation" ], "summary": "List or search the public documentation catalog with docs contract and build metadata.", "security": [], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/docs/index.json": { "get": { "operationId": "get_api_docs_index_json", "tags": [ "Documentation" ], "summary": "Read the public-only documentation content bundle used by static renderers and agents.", "security": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/docs/{id}": { "get": { "operationId": "get_api_docs_id", "tags": [ "Documentation" ], "summary": "Read one public documentation entry as structured JSON.", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/docs/{id}.md": { "get": { "operationId": "get_api_docs_id_md", "tags": [ "Documentation" ], "summary": "Read one public documentation entry as Markdown.", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/docs/feedback": { "post": { "operationId": "post_api_docs_feedback", "tags": [ "Documentation" ], "summary": "Record a text-free helpful, not-helpful, or outdated signal for a current public document and optional heading.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "helpful", "not_helpful", "outdated" ] }, "docId": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 80 }, "sectionId": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 80 } }, "required": [ "kind", "docId" ] }, "example": { "kind": "helpful", "docId": "product-guide", "sectionId": "start-with-a-project" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Feedback body exceeds 4 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Process-local documentation feedback limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds until this process-local window resets.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Documentation telemetry persistence is unavailable; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/docs/selection": { "post": { "operationId": "post_api_docs_selection", "tags": [ "Documentation" ], "summary": "Record a privacy-bounded public document selected from search using only the document id and allowlisted product terms.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "docId": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 80 }, "knownTerms": { "type": "array", "maxItems": 12, "uniqueItems": true, "items": { "type": "string" } } }, "required": [ "docId", "knownTerms" ] }, "example": { "docId": "build-mcp-guide", "knownTerms": [ "build", "mcp" ] } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Selection body exceeds 4 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Process-local documentation selection limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds until this process-local window resets.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Documentation telemetry persistence is unavailable; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/docs/openapi.json": { "get": { "operationId": "get_docs_openapi_json", "tags": [ "Documentation" ], "summary": "Read the generated OpenAPI 3.1 description of supported public endpoints.", "security": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/oauth-protected-resource/mcp/build": { "get": { "operationId": "get_well_known_oauth_protected_resource_mcp_build", "tags": [ "OAuth" ], "summary": "OAuth protected-resource metadata for Topline Build MCP clients.", "security": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/oauth-protected-resource/mcp/workspace": { "get": { "operationId": "get_well_known_oauth_protected_resource_mcp_workspace", "tags": [ "OAuth" ], "summary": "OAuth protected-resource metadata for Topline Workspace MCP clients.", "security": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/oauth-protected-resource/mcp/harness": { "get": { "operationId": "get_well_known_oauth_protected_resource_mcp_harness", "tags": [ "OAuth" ], "summary": "OAuth protected-resource metadata for Harness MCP clients.", "security": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/oauth-protected-resource": { "get": { "operationId": "get_well_known_oauth_protected_resource", "tags": [ "OAuth" ], "summary": "Compatibility alias for Harness OAuth protected-resource metadata.", "security": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/oauth-authorization-server": { "get": { "operationId": "get_well_known_oauth_authorization_server", "tags": [ "OAuth" ], "summary": "OAuth authorization-server metadata and supported scopes.", "security": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/openid-configuration": { "get": { "operationId": "get_well_known_openid_configuration", "tags": [ "OAuth" ], "summary": "Compatibility alias for Harness OAuth authorization-server metadata.", "security": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/oauth/register": { "post": { "operationId": "post_oauth_register", "tags": [ "OAuth" ], "summary": "Register a public OAuth client and approved redirect URIs.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_name": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string", "format": "uri" } }, "grant_types": { "type": "array", "items": { "type": "string" } }, "response_types": { "type": "array", "items": { "type": "string" } }, "token_endpoint_auth_method": { "type": "string", "const": "none" } }, "required": [ "redirect_uris" ] } } } }, "responses": { "201": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/oauth/authorize": { "get": { "operationId": "get_oauth_authorize", "tags": [ "OAuth" ], "summary": "Authorize an MCP client with PKCE and explicit scopes.", "security": [ { "browserSession": [] } ], "parameters": [ { "name": "response_type", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "redirect_uri", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "resource", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "scope", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code_challenge", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code_challenge_method", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/oauth/token": { "post": { "operationId": "post_oauth_token", "tags": [ "OAuth" ], "summary": "Exchange an authorization code or refresh token for an access token.", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/oauth/revoke": { "post": { "operationId": "post_oauth_revoke", "tags": [ "OAuth" ], "summary": "Revoke the OAuth access or refresh token supplied in the request body.", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/mcp/build": { "get": { "operationId": "get_mcp_build", "tags": [ "MCP" ], "summary": "Return the Topline Build MCP identity and artifact tool inventory.", "security": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post_mcp_build", "tags": [ "MCP" ], "summary": "Invoke the Topline Build MCP streamable HTTP endpoint.", "security": [ { "oauth2": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" }, "example": { "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/mcp/workspace": { "get": { "operationId": "get_mcp_workspace", "tags": [ "MCP" ], "summary": "Return the Topline Workspace MCP identity and workspace tool inventory.", "security": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post_mcp_workspace", "tags": [ "MCP" ], "summary": "Invoke the Topline Workspace MCP streamable HTTP endpoint.", "security": [ { "oauth2": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" }, "example": { "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/mcp/harness": { "get": { "operationId": "get_mcp_harness", "tags": [ "MCP" ], "summary": "Return Harness MCP server identity and the unfiltered tool-name inventory.", "security": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "post_mcp_harness", "tags": [ "MCP" ], "summary": "Invoke the streamable HTTP Harness MCP JSON-RPC endpoint.", "security": [ { "oauth2": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" }, "example": { "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/harness/artifact-apps": { "post": { "operationId": "post_api_harness_artifact_apps", "tags": [ "Artifact Apps" ], "summary": "Create or update a private artifact-app draft.", "security": [ { "oauth2": [ "harness:artifact:write" ] }, { "bearerAuth": [] } ], "x-required-scope": "harness:artifact:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ArtifactAppManifestV2" }, { "type": "object", "properties": { "artifactId": { "type": "string" }, "manifest": { "$ref": "#/components/schemas/ArtifactAppManifestV2" }, "title": { "type": "string" }, "description": { "type": "string" }, "projectId": { "type": "string" } }, "required": [ "manifest" ] } ] } } } }, "responses": { "201": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/harness/artifact-apps/{artifactId}/deploy-bundle": { "post": { "operationId": "post_api_harness_artifact_apps_artifactId_deploy_bundle", "tags": [ "Artifact Apps" ], "summary": "Upload and deploy a validated artifact-app tar.gz bundle.", "security": [ { "oauth2": [ "harness:artifact:deploy" ] }, { "bearerAuth": [] } ], "x-required-scope": "harness:artifact:deploy", "parameters": [ { "name": "artifactId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Platform-Artifact-Version-Id", "in": "header", "schema": { "type": "string" } }, { "name": "X-Platform-App-Dir", "in": "header", "schema": { "type": "string", "default": "." } } ], "requestBody": { "required": true, "content": { "application/gzip": { "schema": { "type": "string", "contentEncoding": "base64" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/harness/artifact-apps/{artifactId}/deployments": { "get": { "operationId": "get_api_harness_artifact_apps_artifactId_deployments", "tags": [ "Artifact Apps" ], "summary": "List recent draft deployment state and readiness.", "security": [ { "oauth2": [ "harness:artifact:read" ] }, { "bearerAuth": [] } ], "x-required-scope": "harness:artifact:read", "parameters": [ { "name": "artifactId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/harness/artifact-apps/{artifactId}/logs": { "get": { "operationId": "get_api_harness_artifact_apps_artifactId_logs", "tags": [ "Artifact Apps" ], "summary": "Read bounded and redacted artifact deployment logs.", "security": [ { "oauth2": [ "harness:artifact:read" ] }, { "bearerAuth": [] } ], "x-required-scope": "harness:artifact:read", "parameters": [ { "name": "artifactId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "deploymentRecordId", "in": "query", "schema": { "type": "string" } }, { "name": "environment", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "severity", "in": "query", "schema": { "type": "string" } }, { "name": "contains", "in": "query", "schema": { "type": "string" } }, { "name": "since", "in": "query", "schema": { "type": "string" } }, { "name": "windowMinutes", "in": "query", "schema": { "type": "string" } }, { "name": "trace", "in": "query", "schema": { "type": "string" } }, { "name": "requestId", "in": "query", "schema": { "type": "string" } }, { "name": "route", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/harness-connectors": { "get": { "operationId": "get_api_harness_connectors", "tags": [ "Developer Access" ], "summary": "Read Developer Access configuration and the current operator's connector tokens.", "security": [ { "browserSession": [] } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/harness-connectors/products/{product}/verifications": { "post": { "operationId": "post_api_harness_connectors_products_product_verifications", "tags": [ "Developer Access" ], "summary": "Create a short-lived, product-bound MCP connection verification challenge.", "security": [ { "browserSession": [] } ], "parameters": [ { "name": "product", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/harness-connectors/products/{product}/verifications/{verificationId}": { "get": { "operationId": "get_api_harness_connectors_products_product_verifications_verificationId", "tags": [ "Developer Access" ], "summary": "Read the owner-scoped result of an MCP connection verification challenge.", "security": [ { "browserSession": [] } ], "parameters": [ { "name": "product", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "verificationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/harness-connectors/oauth-authorizations/{authorizationId}/revoke": { "post": { "operationId": "post_api_harness_connectors_oauth_authorizations_authorizationId_revoke", "tags": [ "Developer Access" ], "summary": "Revoke one active OAuth authorization owned by the current operator.", "security": [ { "browserSession": [] } ], "parameters": [ { "name": "authorizationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/harness-connectors/bedrock-token": { "post": { "operationId": "post_api_harness_connectors_bedrock_token", "tags": [ "Developer Access" ], "summary": "Generate a one-hour Bedrock key from the customer-account runtime role.", "security": [ { "browserSession": [] } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/harness-connectors/tokens": { "post": { "operationId": "post_api_harness_connectors_tokens", "tags": [ "Developer Access" ], "summary": "Create a manual fallback connector token.", "security": [ { "browserSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 80 }, "clientKind": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expiresInDays": { "type": "integer", "minimum": 1, "maximum": 180 } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/harness-connectors/tokens/{tokenId}/revoke": { "post": { "operationId": "post_api_harness_connectors_tokens_tokenId_revoke", "tags": [ "Developer Access" ], "summary": "Revoke one connector token owned by the current operator.", "security": [ { "browserSession": [] } ], "parameters": [ { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope, capability, tenant, or resource access is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found within the caller's boundary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected platform failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" }, "browserSession": { "type": "apiKey", "in": "cookie", "name": "platform_session" }, "oauth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://topline.build/oauth/authorize", "tokenUrl": "https://topline.build/oauth/token", "refreshUrl": "https://topline.build/oauth/token", "scopes": { "docs:read": "Search and read documentation.", "chat:read": "List and read conversations visible to the current user.", "harness:artifact:read": "Read artifact status and logs.", "harness:artifact:write": "Create or update artifact drafts.", "harness:artifact:deploy": "Deploy artifact drafts.", "harness:artifact:delete": "Plan and delete eligible private artifact drafts.", "memory:read": "Read approved preferences.", "glossary:read": "Read approved glossary terms." } } } } }, "schemas": { "ArtifactAppManifestV2": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Platform Artifact App Manifest v2", "type": "object", "required": [ "manifestVersion", "id", "title", "kind", "runtime", "build", "validation", "routes", "sourceBindings", "env", "viewerPolicy" ], "additionalProperties": false, "properties": { "manifestVersion": { "const": 2 }, "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "dashboard", "mini_page", "briefing", "table", "tool" ] }, "runtime": { "type": "object", "required": [ "target", "region", "entryPoint" ], "additionalProperties": false, "properties": { "target": { "type": "string", "enum": [ "aws_lambda_function_url" ] }, "region": { "type": "string", "minLength": 1 }, "entryPoint": { "type": "string", "minLength": 1 }, "language": { "type": "string", "enum": [ "node", "python" ] }, "functionName": { "type": "string", "minLength": 1 } } }, "build": { "type": "object", "required": [ "command" ], "additionalProperties": false, "properties": { "command": { "type": "string", "minLength": 1 }, "outputDir": { "type": "string", "minLength": 1 } } }, "validation": { "type": "object", "additionalProperties": false, "properties": { "localCommand": { "type": "string", "minLength": 1 }, "testCommand": { "type": "string", "minLength": 1 } } }, "routes": { "type": "array", "items": { "type": "object", "required": [ "path", "kind" ], "additionalProperties": false, "properties": { "path": { "type": "string", "pattern": "^/" }, "kind": { "type": "string", "enum": [ "page", "api", "asset" ] }, "handler": { "type": "string", "minLength": 1 } } } }, "sourceBindings": { "type": "array", "items": { "type": "object", "required": [ "name", "sourceId", "resource", "mode", "access" ], "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" }, "sourceId": { "type": "string", "minLength": 1 }, "resource": { "type": "string", "minLength": 1 }, "mode": { "type": "string", "enum": [ "live" ] }, "access": { "type": "string", "enum": [ "viewer", "service_aggregate" ] }, "tokenAudience": { "type": "string", "minLength": 1 }, "projection": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "maxRows": { "type": "integer", "minimum": 1, "maximum": 5000 }, "maxBytes": { "type": "integer", "minimum": 10000, "maximum": 5000000 }, "timeoutMs": { "type": "integer", "minimum": 1000, "maximum": 60000 }, "rateLimitPerMinute": { "type": "number", "minimum": 1 }, "viewerRateLimitPerMinute": { "type": "number", "minimum": 1 }, "cacheTtlSeconds": { "type": "number", "minimum": 0 }, "viewerPolicy": { "type": "object", "additionalProperties": false, "properties": { "requiresSession": { "type": "boolean" }, "emailField": { "type": "string", "minLength": 1 } } }, "aggregate": { "type": "object", "additionalProperties": false, "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "count" ] }, "groupBy": { "type": "string", "minLength": 1 }, "countField": { "type": "string", "minLength": 1 } } } } } }, "secretBindings": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "name", "env", "secretArn" ], "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" }, "env": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]*_SECRET_ARN$" }, "secretArn": { "type": "string", "pattern": "^arn:aws(?:-[a-z]+)?:secretsmanager:[a-z0-9-]+:[0-9]{12}:secret:[^\\s*?{}]+$" } } } }, "datasets": { "type": "array", "items": { "type": "object", "required": [ "name", "route", "mode" ], "additionalProperties": false, "allOf": [ { "not": { "required": [ "queryRef", "sql" ] } }, { "if": { "properties": { "mode": { "enum": [ "live", "precomputed" ] } }, "required": [ "mode" ] }, "then": { "required": [ "sql" ] } } ], "properties": { "name": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" }, "route": { "type": "string", "pattern": "^/_artifact/data/[A-Za-z0-9_-]+$" }, "mode": { "type": "string", "enum": [ "live", "precomputed" ] }, "paramsSchema": { "type": "object", "additionalProperties": true }, "warmParams": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "additionalProperties": true } }, "queryRef": { "type": "string", "minLength": 1 }, "sql": { "type": "string", "minLength": 1 }, "maxRows": { "type": "number", "minimum": 1 }, "maxBytes": { "type": "number", "minimum": 1024 }, "timeoutMs": { "type": "number", "minimum": 1 }, "cacheTtlSeconds": { "type": "number", "minimum": 0 } } } }, "refreshSchedules": { "type": "array", "items": { "type": "object", "required": [ "name", "mode", "cron", "timezone", "promptText" ], "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" }, "mode": { "type": "string", "enum": [ "precompute_static", "refresh_live_cache", "maintenance" ] }, "cron": { "type": "string", "minLength": 1 }, "timezone": { "type": "string", "minLength": 1 }, "promptText": { "type": "string", "minLength": 1 }, "outputStrategy": { "type": "string", "enum": [ "new_per_fire", "existing_thread", "silent" ] }, "enabled": { "type": "boolean" }, "scheduleId": { "type": "string", "minLength": 1 } } } }, "env": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "viewerPolicy": { "type": "string", "enum": [ "private", "tenant" ] } } }, "Error": { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "error" ] }, "JsonRpcRequest": { "type": "object", "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "number", "null" ] }, "method": { "type": "string" }, "params": { "type": "object" } }, "required": [ "jsonrpc", "method" ] }, "JsonRpcResponse": { "type": "object", "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "number", "null" ] }, "result": {}, "error": { "type": "object" } }, "required": [ "jsonrpc" ] } } } }