Squad AI

{ "openapi": "3.1.0", "info": { "title": "Squad API", "version": "4.0.0", "description": "API for managing Squad resources", "contact": { "name": "Squad Support", "url": "https://www.meetsquad.ai/support", "email": "help@meetsquad.ai" } }, "servers": [ { "url": "https://api.meetsquad.ai", "description": "Production server" }, { "url": "https://uat.api.meetsquad.ai", "description": "Staging server" }, { "url": "https://dev.api.meetsquad.ai", "description": "Development server" } ], "paths": { "/organisations/{orgId}/workspaces/{workspaceId}/outcomes": { "post": { "operationId": "createOutcome", "summary": "Create a new outcome", "description": "Create a new outcome in the specified workspace", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOutcomePayload" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "Response containing a single outcome", "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OutcomeWithRelationships" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input parameters or missing required fields", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INVALID_REQUEST", "type": "string" }, "description": { "description": "Human-readable error description", "example": "One or more fields are invalid", "type": "string" }, "fields": { "description": "List of field names that are missing or invalid", "example": [ "title", "description" ], "type": "array", "items": { "type": "string" } }, "validationErrors": { "description": "Detailed validation error information for each invalid field", "example": { "invalidFields": { "title": { "type": "too_small", "message": "Title must be at least 3 characters long", "path": [ "title" ] }, "deadline": { "type": "invalid_date", "message": "Deadline must be a valid date in the future", "path": [ "deadline" ] } } }, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "get": { "operationId": "listOutcomes", "summary": "List all outcomes", "description": "Retrieve a list of all outcomes in the specified workspace", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "Response containing an array of outcomes", "type": "object", "properties": { "data": { "description": "Array of outcomes", "type": "array", "items": { "$ref": "#/components/schemas/Outcome" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/outcomes/{outcomeId}": { "get": { "operationId": "getOutcome", "summary": "Get an outcome by ID", "description": "Retrieve a specific outcome by its ID", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "outcomeId", "schema": { "type": "string" }, "required": true, "description": "Outcome ID", "example": "7b9e5d2c-f314-48a9-be56-9843a2f6c019" }, { "$ref": "#/components/parameters/OutcomeRelationshipsParam" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "Response containing a single outcome", "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OutcomeWithRelationships" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input parameters or missing required fields", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INVALID_REQUEST", "type": "string" }, "description": { "description": "Human-readable error description", "example": "One or more fields are invalid", "type": "string" }, "fields": { "description": "List of field names that are missing or invalid", "example": [ "title", "description" ], "type": "array", "items": { "type": "string" } }, "validationErrors": { "description": "Detailed validation error information for each invalid field", "example": { "invalidFields": { "title": { "type": "too_small", "message": "Title must be at least 3 characters long", "path": [ "title" ] }, "deadline": { "type": "invalid_date", "message": "Deadline must be a valid date in the future", "path": [ "deadline" ] } } }, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Not Found - Outcome does not exist", "content": { "application/json": { "schema": { "description": "Not Found - The requested resource does not exist", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "NOT_FOUND", "type": "string" }, "description": { "description": "Human-readable error description", "example": "The requested resource was not found", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "put": { "operationId": "updateOutcome", "summary": "Update an outcome", "description": "Update an existing outcome by its ID", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "outcomeId", "schema": { "type": "string" }, "required": true, "description": "Outcome ID", "example": "7b9e5d2c-f314-48a9-be56-9843a2f6c019" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOutcomePayload" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "Response containing a single outcome", "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OutcomeWithRelationships" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input parameters or missing required fields", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INVALID_REQUEST", "type": "string" }, "description": { "description": "Human-readable error description", "example": "One or more fields are invalid", "type": "string" }, "fields": { "description": "List of field names that are missing or invalid", "example": [ "title", "description" ], "type": "array", "items": { "type": "string" } }, "validationErrors": { "description": "Detailed validation error information for each invalid field", "example": { "invalidFields": { "title": { "type": "too_small", "message": "Title must be at least 3 characters long", "path": [ "title" ] }, "deadline": { "type": "invalid_date", "message": "Deadline must be a valid date in the future", "path": [ "deadline" ] } } }, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Not Found - Outcome does not exist", "content": { "application/json": { "schema": { "description": "Not Found - The requested resource does not exist", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "NOT_FOUND", "type": "string" }, "description": { "description": "Human-readable error description", "example": "The requested resource was not found", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "delete": { "operationId": "deleteOutcome", "summary": "Delete an outcome", "description": "Delete an existing outcome by its ID", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "outcomeId", "schema": { "type": "string" }, "required": true, "description": "Outcome ID", "example": "7b9e5d2c-f314-48a9-be56-9843a2f6c019" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "Response containing a success message", "type": "object", "properties": { "data": { "description": "Success message data", "type": "object", "properties": { "message": { "description": "Success message", "example": "Outcome deleted successfully", "type": "string" } }, "required": [ "message" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Not Found - Outcome does not exist", "content": { "application/json": { "schema": { "description": "Not Found - The requested resource does not exist", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "NOT_FOUND", "type": "string" }, "description": { "description": "Human-readable error description", "example": "The requested resource was not found", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/metrics": { "post": { "operationId": "createMetric", "summary": "Create a new metric", "description": "Creates a new metric.", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMetricPayload" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "Response containing a single metric", "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Metric" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input parameters or missing required fields", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INVALID_REQUEST", "type": "string" }, "description": { "description": "Human-readable error description", "example": "One or more fields are invalid", "type": "string" }, "fields": { "description": "List of field names that are missing or invalid", "example": [ "title", "description" ], "type": "array", "items": { "type": "string" } }, "validationErrors": { "description": "Detailed validation error information for each invalid field", "example": { "invalidFields": { "title": { "type": "too_small", "message": "Title must be at least 3 characters long", "path": [ "title" ] }, "deadline": { "type": "invalid_date", "message": "Deadline must be a valid date in the future", "path": [ "deadline" ] } } }, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "get": { "operationId": "listMetrics", "summary": "List metrics", "description": "Lists metrics for a workspace. Can optionally filter by outcome ID.", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "query", "name": "outcomeId", "schema": { "type": "string" }, "required": false, "description": "Optional outcome ID to filter metrics by. If omitted, returns all metrics for the workspace.", "example": "7b9e5d2c-f314-48a9-be56-9843a2f6c019" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "Response containing an array of metrics", "type": "object", "properties": { "data": { "description": "Array of metrics", "type": "array", "items": { "$ref": "#/components/schemas/Metric" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input parameters or missing required fields", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INVALID_REQUEST", "type": "string" }, "description": { "description": "Human-readable error description", "example": "One or more fields are invalid", "type": "string" }, "fields": { "description": "List of field names that are missing or invalid", "example": [ "title", "description" ], "type": "array", "items": { "type": "string" } }, "validationErrors": { "description": "Detailed validation error information for each invalid field", "example": { "invalidFields": { "title": { "type": "too_small", "message": "Title must be at least 3 characters long", "path": [ "title" ] }, "deadline": { "type": "invalid_date", "message": "Deadline must be a valid date in the future", "path": [ "deadline" ] } } }, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/metrics/{MetricId}": { "get": { "operationId": "getMetric", "summary": "Get a metric by ID", "description": "Retrieves a specific metric by ID.", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "MetricId", "schema": { "type": "string" }, "required": true, "description": " Metric ID", "example": "7b9e5d2c-f314-48a9-be56-9843a2f6c019" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "Response containing a single metric", "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Metric" } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Not Found - metric does not exist", "content": { "application/json": { "schema": { "description": "Not Found - The requested resource does not exist", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "NOT_FOUND", "type": "string" }, "description": { "description": "Human-readable error description", "example": "The requested resource was not found", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "put": { "operationId": "updateMetric", "summary": "Update a metric", "description": "Updates an existing metric.", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "MetricId", "schema": { "type": "string" }, "required": true, "description": " Metric ID", "example": "7b9e5d2c-f314-48a9-be56-9843a2f6c019" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMetricPayload" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "Response containing a single metric", "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Metric" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input parameters or missing required fields", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INVALID_REQUEST", "type": "string" }, "description": { "description": "Human-readable error description", "example": "One or more fields are invalid", "type": "string" }, "fields": { "description": "List of field names that are missing or invalid", "example": [ "title", "description" ], "type": "array", "items": { "type": "string" } }, "validationErrors": { "description": "Detailed validation error information for each invalid field", "example": { "invalidFields": { "title": { "type": "too_small", "message": "Title must be at least 3 characters long", "path": [ "title" ] }, "deadline": { "type": "invalid_date", "message": "Deadline must be a valid date in the future", "path": [ "deadline" ] } } }, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Not Found - metric does not exist", "content": { "application/json": { "schema": { "description": "Not Found - The requested resource does not exist", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "NOT_FOUND", "type": "string" }, "description": { "description": "Human-readable error description", "example": "The requested resource was not found", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "delete": { "operationId": "deleteMetric", "summary": "Delete a metric", "description": "Deletes an existing metric and cleans up associated resources.", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "MetricId", "schema": { "type": "string" }, "required": true, "description": " Metric ID", "example": "7b9e5d2c-f314-48a9-be56-9843a2f6c019" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "Response containing a success message", "type": "object", "properties": { "data": { "description": "Success message data", "type": "object", "properties": { "success": { "description": "Success flag", "example": true, "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Not Found - metric does not exist", "content": { "application/json": { "schema": { "description": "Not Found - The requested resource does not exist", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "NOT_FOUND", "type": "string" }, "description": { "description": "Human-readable error description", "example": "The requested resource was not found", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/metrics/{metricId}/relationships/{action}": { "post": { "operationId": "manageMetricRelationships", "summary": "Manage metric relationships", "description": "Add or remove relationships between a metric and other entities (outcomes)", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "metricId", "schema": { "type": "string" }, "required": true, "description": "Metric ID", "example": "7b9e5d2c-f314-48a9-be56-9843a2f6c019" }, { "in": "path", "name": "action", "schema": { "param": { "name": "action", "in": "path", "required": true, "description": "Action to perform on relationships", "example": "add" }, "$ref": "#/components/schemas/RelationshipAction" }, "required": true, "description": "Action to perform on relationships", "example": "add" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricRelationshipsPayload" } } } }, "responses": { "204": { "description": "Relationships successfully modified" }, "400": { "description": "Bad request - invalid input parameters" }, "401": { "description": "Unauthorized - invalid or missing authentication" }, "404": { "description": "Resource not found" }, "500": { "description": "Internal server error" } } } }, "/onboard": { "post": { "operationId": "onboardOrganisation", "summary": "Create a new organization with workspace and outcomes", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingPayload" } } } }, "responses": { "200": { "description": "Organization, workspace, and outcomes created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingResponse" } } } }, "400": { "description": "Invalid request body" }, "409": { "description": "Organization name already exists" } } } }, "/organisations/{orgId}/onboard": { "put": { "operationId": "updateOnboarding", "summary": "Update an existing organization, recreate workspace and outcomes", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingUpdatePayload" } } } }, "responses": { "200": { "description": "Organization updated, workspace and outcomes recreated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingResponse" } } } }, "400": { "description": "Invalid request body" }, "404": { "description": "Organization not found" } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/onboarding": { "post": { "operationId": "onboardWorkspaceV2", "summary": "Process business description and knowledge to create workspace details, outcomes, opportunities, and solutions", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "b7e2d5a9-3c18-4e6f-9a42-f8d1c7b5e3a2" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingV2Payload" } } } }, "responses": { "204": { "description": "Request accepted, processing started" }, "400": { "description": "Invalid request body" }, "404": { "description": "One or more knowledge entities not found" } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/feedback": { "post": { "operationId": "createFeedback", "summary": "Create new feedback", "description": "Creates a new feedback item in the specified workspace and automatically queues it for processing", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFeedbackRequest" } } } }, "responses": { "200": { "description": "Feedback created successfully", "content": { "application/json": { "schema": { "description": "Response containing a single feedback item", "type": "object", "properties": { "data": { "description": "Feedback data", "$ref": "#/components/schemas/FeedbackWithRelationships" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input parameters or missing required fields", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INVALID_REQUEST", "type": "string" }, "description": { "description": "Human-readable error description", "example": "One or more fields are invalid", "type": "string" }, "fields": { "description": "List of field names that are missing or invalid", "example": [ "title", "description" ], "type": "array", "items": { "type": "string" } }, "validationErrors": { "description": "Detailed validation error information for each invalid field", "example": { "invalidFields": { "title": { "type": "too_small", "message": "Title must be at least 3 characters long", "path": [ "title" ] }, "deadline": { "type": "invalid_date", "message": "Deadline must be a valid date in the future", "path": [ "deadline" ] } } }, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "get": { "operationId": "listFeedback", "summary": "List feedback", "description": "Lists all feedback in the specified workspace", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackArrayResponse" } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/feedback/{feedbackId}": { "get": { "operationId": "getFeedback", "summary": "Get feedback by ID", "description": "Retrieves a specific feedback by ID", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "feedbackId", "schema": { "type": "string" }, "required": true, "description": "Feedback ID", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4" }, { "$ref": "#/components/parameters/FeedbackRelationshipsParam" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "Response containing a single feedback item", "type": "object", "properties": { "data": { "description": "Feedback data", "$ref": "#/components/schemas/FeedbackWithRelationships" } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Feedback not found", "content": { "application/json": { "schema": { "description": "Not Found - The requested resource does not exist", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "NOT_FOUND", "type": "string" }, "description": { "description": "Human-readable error description", "example": "The requested resource was not found", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "delete": { "operationId": "deleteFeedback", "summary": "Delete feedback", "description": "Deletes a specific feedback by ID", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "feedbackId", "schema": { "type": "string" }, "required": true, "description": "Feedback ID", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4" } ], "responses": { "200": { "description": "Feedback deleted successfully", "content": { "application/json": { "schema": { "description": "Response containing a success message", "type": "object", "properties": { "data": { "description": "Success message data", "type": "object", "properties": { "message": { "description": "Success message", "example": "Feedback deleted successfully", "type": "string" } }, "required": [ "message" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Feedback not found", "content": { "application/json": { "schema": { "description": "Not Found - The requested resource does not exist", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "NOT_FOUND", "type": "string" }, "description": { "description": "Human-readable error description", "example": "The requested resource was not found", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/insights": { "post": { "operationId": "createInsight", "tags": [ "Squad" ], "summary": "Create new insight", "description": "Creates a new insight item in the specified workspace", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "type": { "description": "Type of insight", "example": "Feedback", "type": "string", "enum": [ "Feedback", "Bug", "FeatureRequest" ] }, "title": { "description": "Title of the insight", "example": "Dashboard UX Improvements", "type": "string" }, "description": { "description": "Description of the insight", "example": "The dashboard could use better data visualization", "type": "string" }, "ownerId": { "description": "ID of the insight owner", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4", "type": "string" }, "strengthScore": { "description": "Wilson score + corroboration score (0-1)", "example": 0.75, "type": "number", "minimum": 0, "maximum": 1 }, "momentumScore": { "description": "Recency and burst detection score", "example": 0.5, "type": "number", "minimum": 0 }, "combinedScore": { "description": "Weighted composite of strength and momentum scores", "example": 0.65, "type": "number", "minimum": 0 }, "lastScoreCalculatedAt": { "description": "ISO timestamp of last score calculation", "example": "2025-03-26T22:35:46Z", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "topicEmbeddings": { "description": "BERT embeddings for topic modeling", "example": [ 0.1, -0.2, 0.3 ], "type": "array", "items": { "type": "number" } }, "organisationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "workspaceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "seen": { "type": "boolean" }, "feedbackIds": { "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } }, "required": [ "type", "title", "description", "organisationId", "workspaceId" ] } } } }, "responses": { "200": { "description": "Insight created successfully", "content": { "application/json": { "schema": { "description": "Response containing a single insight item", "type": "object", "properties": { "data": { "description": "Insight data", "$ref": "#/components/schemas/InsightWithRelationships" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input parameters or missing required fields", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INVALID_REQUEST", "type": "string" }, "description": { "description": "Human-readable error description", "example": "One or more fields are invalid", "type": "string" }, "fields": { "description": "List of field names that are missing or invalid", "example": [ "title", "description" ], "type": "array", "items": { "type": "string" } }, "validationErrors": { "description": "Detailed validation error information for each invalid field", "example": { "invalidFields": { "title": { "type": "too_small", "message": "Title must be at least 3 characters long", "path": [ "title" ] }, "deadline": { "type": "invalid_date", "message": "Deadline must be a valid date in the future", "path": [ "deadline" ] } } }, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "get": { "operationId": "listInsights", "tags": [ "Squad" ], "summary": "List insights", "description": "Lists all insights in the specified workspace", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsightArrayResponse" } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/insights/{insightId}": { "get": { "operationId": "getInsight", "tags": [ "Squad" ], "summary": "Get insight by ID", "description": "Retrieves a specific insight by ID", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "insightId", "schema": { "type": "string" }, "required": true, "description": "Insight ID", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4" }, { "$ref": "#/components/parameters/InsightRelationshipsParam" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "Response containing a single insight item", "type": "object", "properties": { "data": { "description": "Insight data", "$ref": "#/components/schemas/InsightWithRelationships" } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Insight not found", "content": { "application/json": { "schema": { "description": "Not Found - The requested resource does not exist", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "NOT_FOUND", "type": "string" }, "description": { "description": "Human-readable error description", "example": "The requested resource was not found", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "delete": { "operationId": "deleteInsight", "tags": [ "Squad" ], "summary": "Delete insight", "description": "Deletes a specific insight by ID", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "insightId", "schema": { "type": "string" }, "required": true, "description": "Insight ID", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4" } ], "responses": { "200": { "description": "Insight deleted successfully", "content": { "application/json": { "schema": { "description": "Response containing a success message", "type": "object", "properties": { "data": { "description": "Success message data", "type": "object", "properties": { "message": { "description": "Success message", "example": "Insight deleted successfully", "type": "string" } }, "required": [ "message" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Insight not found", "content": { "application/json": { "schema": { "description": "Not Found - The requested resource does not exist", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "NOT_FOUND", "type": "string" }, "description": { "description": "Human-readable error description", "example": "The requested resource was not found", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/mock-insights": { "post": { "operationId": "generateMockInsights", "tags": [ "Squad" ], "summary": "Generate mock insights", "description": "Generates mock insights for testing purposes", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "responses": { "200": { "description": "Mock insights generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MockInsightsResponse" } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/org/{orgId}/workspace/{workspaceId}/integration": { "post": { "summary": "Create a new integration", "description": "Creates a new integration for the workspace, storing any secrets securely in AWS Secrets Manager", "operationId": "createIntegration", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIntegrationPayload" }, "examples": { "notion": { "summary": "Create Notion integration", "value": { "integrationId": "NOTION", "config": { "apiKey": "secret_abc123..." } } }, "typeform": { "summary": "Create Typeform integration", "value": { "integrationId": "TYPEFORM", "config": { "secret": "webhook_secret_xyz" } } }, "playStoreReviews": { "summary": "Create Play Store Reviews integration", "value": { "integrationId": "PLAY_STORE_REVIEWS", "config": { "app_id": "com.google.android.googlequicksearchbox", "country": "us", "app_name": "Google", "image_url": "https://play-lh.googleusercontent.com/aFWiT2lTa9CYBpyPjfgfNHd0r5puwKRGj2rHpdPTNrz2N9LXgN_MbLjePd1OTc0E8Rl1", "active": true } } } } } } }, "responses": { "200": { "description": "Integration created successfully", "content": { "application/json": { "schema": { "description": "Response containing a single integration", "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Integration" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" } } }, "get": { "summary": "List all integrations", "description": "Returns all integrations for the workspace", "operationId": "listIntegrations", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "responses": { "200": { "description": "List of integrations", "content": { "application/json": { "schema": { "description": "Response containing an array of integrations", "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized" } } } }, "/org/{orgId}/workspace/{workspaceId}/integration/{integrationId}": { "get": { "summary": "Get integration by ID", "description": "Returns a single integration by its ID", "operationId": "getIntegration", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "integrationId", "schema": { "type": "number" }, "required": true, "description": "Integration record ID" } ], "responses": { "200": { "description": "Integration details", "content": { "application/json": { "schema": { "description": "Response containing a single integration", "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Integration" } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Integration not found" } } }, "patch": { "summary": "Update an integration", "description": "Updates an integration configuration, including re-entering secrets", "operationId": "updateIntegration", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "integrationId", "schema": { "type": "number" }, "required": true, "description": "Integration record ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateIntegrationPayload" }, "examples": { "notion": { "summary": "Update Notion API key", "value": { "config": { "apiKey": "secret_new123..." } } } } } } }, "responses": { "200": { "description": "Integration updated successfully", "content": { "application/json": { "schema": { "description": "Response containing a single integration", "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Integration" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Integration not found" } } }, "delete": { "summary": "Delete an integration", "description": "Deletes an integration and cleans up any associated secrets", "operationId": "deleteIntegration", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "integrationId", "schema": { "type": "number" }, "required": true, "description": "Integration record ID" } ], "responses": { "204": { "description": "Integration deleted successfully" }, "401": { "description": "Unauthorized" }, "404": { "description": "Integration not found" } } } }, "/org/{orgId}/workspace/{workspaceId}/integration/{integrationId}/sync": { "post": { "summary": "Initiate Notion integration sync", "operationId": "syncIntegration", "tags": [ "Squad" ], "description": "Triggers a sync operation for a Notion integration, queuing all configured pages for processing", "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "integrationId", "schema": { "type": "number" }, "required": true, "description": "Integration ID", "example": 117 } ], "responses": { "202": { "description": "Sync accepted and queued for processing", "content": { "application/json": { "schema": { "description": "Response from sync initiation", "type": "object", "properties": { "data": { "type": "object", "properties": { "message": { "description": "Status message", "example": "Sync initiated", "type": "string" }, "upsertCount": { "description": "Number of pages to be created or updated", "example": 10, "type": "number" }, "deleteCount": { "description": "Number of pages to be deleted", "example": 2, "type": "number" }, "integrationId": { "description": "Integration ID", "example": 117, "type": "number" } }, "required": [ "message", "upsertCount", "deleteCount", "integrationId" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request - Invalid integration type or inactive" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Integration not found" }, "500": { "description": "Internal server error - Queue configuration issue" } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/opportunities": { "post": { "operationId": "createOpportunity", "summary": "Create new opportunity", "description": "Creates a new opportunity in the specified workspace", "tags": [ "Squad" ], "security": [ { "bearerAuth": [], "apiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOpportunityPayload" } } } }, "responses": { "200": { "description": "Opportunity created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityResponse" } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input parameters or missing required fields", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INVALID_REQUEST", "type": "string" }, "description": { "description": "Human-readable error description", "example": "One or more fields are invalid", "type": "string" }, "fields": { "description": "List of field names that are missing or invalid", "example": [ "title", "description" ], "type": "array", "items": { "type": "string" } }, "validationErrors": { "description": "Detailed validation error information for each invalid field", "example": { "invalidFields": { "title": { "type": "too_small", "message": "Title must be at least 3 characters long", "path": [ "title" ] }, "deadline": { "type": "invalid_date", "message": "Deadline must be a valid date in the future", "path": [ "deadline" ] } } }, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Too Many Requests - Rate limit or entity limit exceeded", "content": { "application/json": { "schema": { "description": "Too Many Requests - Rate limit exceeded", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "TOO_MANY_REQUESTS", "type": "string" }, "description": { "description": "Human-readable error description", "example": "Rate limit exceeded", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "get": { "operationId": "listOpportunities", "summary": "List opportunities", "description": "Lists all opportunities in the specified workspace", "tags": [ "Squad" ], "security": [ { "bearerAuth": [], "apiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityArrayResponse" } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/opportunities/{opportunityId}": { "get": { "operationId": "getOpportunity", "summary": "Get opportunity by ID", "description": "Retrieves a specific opportunity by ID", "tags": [ "Squad" ], "security": [ { "bearerAuth": [], "apiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "opportunityId", "schema": { "type": "string" }, "required": true, "description": "Opportunity ID", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4" }, { "$ref": "#/components/parameters/OpportunityRelationshipsParam" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityResponse" } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Opportunity not found", "content": { "application/json": { "schema": { "description": "Not Found - The requested resource does not exist", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "NOT_FOUND", "type": "string" }, "description": { "description": "Human-readable error description", "example": "The requested resource was not found", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "put": { "operationId": "updateOpportunity", "summary": "Update opportunity", "description": "Updates a specific opportunity by ID", "tags": [ "Squad" ], "security": [ { "bearerAuth": [], "apiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "opportunityId", "schema": { "type": "string" }, "required": true, "description": "Opportunity ID", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOpportunityPayload" } } } }, "responses": { "200": { "description": "Opportunity updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityResponse" } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input parameters or missing required fields", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INVALID_REQUEST", "type": "string" }, "description": { "description": "Human-readable error description", "example": "One or more fields are invalid", "type": "string" }, "fields": { "description": "List of field names that are missing or invalid", "example": [ "title", "description" ], "type": "array", "items": { "type": "string" } }, "validationErrors": { "description": "Detailed validation error information for each invalid field", "example": { "invalidFields": { "title": { "type": "too_small", "message": "Title must be at least 3 characters long", "path": [ "title" ] }, "deadline": { "type": "invalid_date", "message": "Deadline must be a valid date in the future", "path": [ "deadline" ] } } }, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Opportunity not found", "content": { "application/json": { "schema": { "description": "Not Found - The requested resource does not exist", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "NOT_FOUND", "type": "string" }, "description": { "description": "Human-readable error description", "example": "The requested resource was not found", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "delete": { "operationId": "deleteOpportunity", "summary": "Delete opportunity", "description": "Deletes a specific opportunity by ID", "tags": [ "Squad" ], "security": [ { "bearerAuth": [], "apiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "opportunityId", "schema": { "type": "string" }, "required": true, "description": "Opportunity ID", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4" } ], "responses": { "200": { "description": "Opportunity deleted successfully", "content": { "application/json": { "schema": { "description": "Response containing a success message", "type": "object", "properties": { "data": { "description": "Success message data", "type": "object", "properties": { "message": { "description": "Success message", "example": "Opportunity deleted successfully", "type": "string" } }, "required": [ "message" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Opportunity not found", "content": { "application/json": { "schema": { "description": "Not Found - The requested resource does not exist", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "NOT_FOUND", "type": "string" }, "description": { "description": "Human-readable error description", "example": "The requested resource was not found", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/solutions": { "post": { "operationId": "createSolution", "summary": "Create new solution", "description": "Creates a new solution in the specified workspace", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSolutionPayload" } } } }, "responses": { "200": { "description": "Solution created successfully", "content": { "application/json": { "schema": { "description": "Response containing a single solution", "type": "object", "properties": { "data": { "description": "Solution data", "$ref": "#/components/schemas/SolutionWithRelationships" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" } } }, "get": { "operationId": "listSolutions", "summary": "List solutions", "description": "Lists all solutions in the specified workspace with optional filtering", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "query", "name": "built", "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "description": "Filter solutions by whether they have been built (modified after creation)", "example": "true" }, { "in": "query", "name": "status", "schema": { "type": "string", "pattern": "^(Backlog|New|Planned|InDevelopment|Complete|Cancelled)(,(Backlog|New|Planned|InDevelopment|Complete|Cancelled))*$" }, "required": false, "description": "Comma-separated list of solution statuses to filter by", "example": "Backlog,New,Planned" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "Response containing an array of solutions", "type": "object", "properties": { "data": { "description": "Array of solutions", "type": "array", "items": { "$ref": "#/components/schemas/SolutionWithRelationships" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/solutions/{solutionId}": { "get": { "operationId": "getSolution", "summary": "Get solution by ID", "description": "Retrieves a specific solution by ID", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "solutionId", "schema": { "type": "string" }, "required": true, "description": "Solution ID", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4" }, { "$ref": "#/components/parameters/SolutionRelationshipsParam" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "Response containing a single solution", "type": "object", "properties": { "data": { "description": "Solution data", "$ref": "#/components/schemas/SolutionWithRelationships" } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Solution not found" } } }, "put": { "operationId": "updateSolution", "summary": "Update solution", "description": "Updates a specific solution by ID", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "solutionId", "schema": { "type": "string" }, "required": true, "description": "Solution ID", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSolutionPayload" } } } }, "responses": { "200": { "description": "Solution updated successfully", "content": { "application/json": { "schema": { "description": "Response containing a single solution", "type": "object", "properties": { "data": { "description": "Solution data", "$ref": "#/components/schemas/SolutionWithRelationships" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Solution not found" } } }, "delete": { "operationId": "deleteSolution", "summary": "Delete solution", "description": "Deletes a specific solution by ID", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "solutionId", "schema": { "type": "string" }, "required": true, "description": "Solution ID", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4" } ], "responses": { "200": { "description": "Solution deleted successfully", "content": { "application/json": { "schema": { "description": "Response containing a success message", "type": "object", "properties": { "data": { "description": "Success message data", "type": "object", "properties": { "message": { "description": "Success message", "example": "Solution deleted successfully", "type": "string" } }, "required": [ "message" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Solution not found" } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/topics": { "post": { "operationId": "createTopic", "summary": "Create new topic", "description": "Creates a new topic in the specified workspace", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTopicPayload" } } } }, "responses": { "200": { "description": "Topic created successfully", "content": { "application/json": { "schema": { "description": "Response containing a single topic", "type": "object", "properties": { "data": { "description": "Topic data", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "description": "Title of the topic", "example": "User Interface Improvements", "type": "string" }, "description": { "description": "Description of the topic", "example": "General insight related to UI/UX improvements", "type": "string" }, "createdAt": { "description": "Creation timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "updatedAt": { "description": "Last update timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "opportunities": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Opportunity" } }, "insights": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Insight" } } }, "required": [ "id", "title", "description", "createdAt", "updatedAt", "opportunities", "insights" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" } } }, "get": { "operationId": "listTopics", "summary": "List topics", "description": "Lists all topics in the specified workspace", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "Response containing an array of topics", "type": "object", "properties": { "data": { "description": "Array of topics", "type": "array", "items": { "$ref": "#/components/schemas/TopicWithRelationships" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/topics/{topicId}": { "get": { "operationId": "getTopic", "summary": "Get topic by ID", "description": "Retrieves a specific topic by ID", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "topicId", "schema": { "type": "string" }, "required": true, "description": "Topic ID", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "Response containing a single topic", "type": "object", "properties": { "data": { "description": "Topic data", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "description": "Title of the topic", "example": "User Interface Improvements", "type": "string" }, "description": { "description": "Description of the topic", "example": "General insight related to UI/UX improvements", "type": "string" }, "createdAt": { "description": "Creation timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "updatedAt": { "description": "Last update timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "opportunities": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Opportunity" } }, "insights": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Insight" } } }, "required": [ "id", "title", "description", "createdAt", "updatedAt", "opportunities", "insights" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Topic not found" } } }, "put": { "operationId": "updateTopic", "summary": "Update topic", "description": "Updates a specific topic by ID", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "topicId", "schema": { "type": "string" }, "required": true, "description": "Topic ID", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTopicPayload" } } } }, "responses": { "200": { "description": "Topic updated successfully", "content": { "application/json": { "schema": { "description": "Response containing a single topic", "type": "object", "properties": { "data": { "description": "Topic data", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "description": "Title of the topic", "example": "User Interface Improvements", "type": "string" }, "description": { "description": "Description of the topic", "example": "General insight related to UI/UX improvements", "type": "string" }, "createdAt": { "description": "Creation timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "updatedAt": { "description": "Last update timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "opportunities": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Opportunity" } }, "insights": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Insight" } } }, "required": [ "id", "title", "description", "createdAt", "updatedAt", "opportunities", "insights" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Topic not found" } } }, "delete": { "operationId": "deleteTopic", "summary": "Delete topic", "description": "Deletes a specific topic by ID", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "topicId", "schema": { "type": "string" }, "required": true, "description": "Topic ID", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4" } ], "responses": { "200": { "description": "Topic deleted successfully", "content": { "application/json": { "schema": { "description": "Response containing a success message", "type": "object", "properties": { "data": { "description": "Success message data", "type": "object", "properties": { "message": { "description": "Success message", "example": "Topic deleted successfully", "type": "string" } }, "required": [ "message" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Topic not found" } } } }, "/organisations/{orgId}/workspaces": { "post": { "operationId": "createWorkspace", "summary": "Create new workspace", "description": "Creates a new workspace for the specified organization", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkspacePayload" } } } }, "responses": { "200": { "description": "Workspace created successfully", "content": { "application/json": { "schema": { "description": "Response containing a single workspace", "type": "object", "properties": { "data": { "description": "Workspace data", "$ref": "#/components/schemas/Workspace" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input parameters or missing required fields", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INVALID_REQUEST", "type": "string" }, "description": { "description": "Human-readable error description", "example": "One or more fields are invalid", "type": "string" }, "fields": { "description": "List of field names that are missing or invalid", "example": [ "title", "description" ], "type": "array", "items": { "type": "string" } }, "validationErrors": { "description": "Detailed validation error information for each invalid field", "example": { "invalidFields": { "title": { "type": "too_small", "message": "Title must be at least 3 characters long", "path": [ "title" ] }, "deadline": { "type": "invalid_date", "message": "Deadline must be a valid date in the future", "path": [ "deadline" ] } } }, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "get": { "operationId": "listWorkspaces", "summary": "List workspaces", "description": "Lists all workspaces for the specified organization", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "Response containing an array of workspaces", "type": "object", "properties": { "data": { "description": "Array of workspaces", "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/organisations/{orgId}/workspaces/{workspaceId}": { "get": { "operationId": "getWorkspace", "summary": "Get workspace by ID", "description": "Retrieves a specific workspace by ID", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "Response containing a single workspace", "type": "object", "properties": { "data": { "description": "Workspace data", "$ref": "#/components/schemas/Workspace" } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "description": "Not Found - The requested resource does not exist", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "NOT_FOUND", "type": "string" }, "description": { "description": "Human-readable error description", "example": "The requested resource was not found", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "put": { "operationId": "updateWorkspace", "summary": "Update workspace", "description": "Updates a specific workspace by ID", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorkspacePayload" } } } }, "responses": { "200": { "description": "Workspace updated successfully", "content": { "application/json": { "schema": { "description": "Response containing a single workspace", "type": "object", "properties": { "data": { "description": "Workspace data", "$ref": "#/components/schemas/Workspace" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input parameters or missing required fields", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INVALID_REQUEST", "type": "string" }, "description": { "description": "Human-readable error description", "example": "One or more fields are invalid", "type": "string" }, "fields": { "description": "List of field names that are missing or invalid", "example": [ "title", "description" ], "type": "array", "items": { "type": "string" } }, "validationErrors": { "description": "Detailed validation error information for each invalid field", "example": { "invalidFields": { "title": { "type": "too_small", "message": "Title must be at least 3 characters long", "path": [ "title" ] }, "deadline": { "type": "invalid_date", "message": "Deadline must be a valid date in the future", "path": [ "deadline" ] } } }, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "description": "Not Found - The requested resource does not exist", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "NOT_FOUND", "type": "string" }, "description": { "description": "Human-readable error description", "example": "The requested resource was not found", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "delete": { "operationId": "deleteWorkspace", "summary": "Delete workspace", "description": "Deletes a specific workspace by ID", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "responses": { "200": { "description": "Workspace deleted successfully", "content": { "application/json": { "schema": { "description": "Response containing a success message", "type": "object", "properties": { "data": { "description": "Success message data", "type": "object", "properties": { "message": { "description": "Success message", "example": "Workspace deleted successfully", "type": "string" } }, "required": [ "message" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Workspace not found", "content": { "application/json": { "schema": { "description": "Not Found - The requested resource does not exist", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "NOT_FOUND", "type": "string" }, "description": { "description": "Human-readable error description", "example": "The requested resource was not found", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/organisations": { "post": { "operationId": "createOrganisation", "summary": "Create new organisation", "description": "Creates a new organisation", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganisationPayload" } } } }, "responses": { "200": { "description": "Organisation created successfully", "content": { "application/json": { "schema": { "description": "Response containing a single organisation", "type": "object", "properties": { "data": { "description": "Organisation data", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "description": "Name of the organisation", "example": "Acme Corporation", "type": "string" }, "stripeCustomerId": { "description": "Stripe customer ID for billing", "example": "cus_1234567890", "type": "string" }, "homepageUrl": { "description": "URL to the organisation's homepage", "example": "https://acme.example.com", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "logoUrl": { "description": "URL to the organisation's logo", "example": "https://acme.example.com/logo.png", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "description": "Creation timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "accountType": { "description": "Account type", "example": "HOBBY", "$ref": "#/components/schemas/OrganisationAccountTypeEnum" }, "billingCycleStartDate": { "description": "The start date of the current billing cycle.", "example": "2025-03-26T22:35:46Z", "type": "string" }, "billingCycleFlexCreditAllowance": { "description": "Number of flex credits available at the start of the current billing cycle.", "example": 100000, "type": "number" }, "updatedAt": { "description": "Last update timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "status": { "description": "Status of the organisation", "example": "ACTIVE", "default": "ACTIVE", "type": "string", "enum": [ "ACTIVE", "ARCHIVED" ] }, "unprocessedFeedbackCount": { "$ref": "#/components/schemas/Organisation" } }, "required": [ "id", "name", "createdAt", "accountType", "billingCycleStartDate", "billingCycleFlexCreditAllowance", "updatedAt", "status", "unprocessedFeedbackCount" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input parameters or missing required fields", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INVALID_REQUEST", "type": "string" }, "description": { "description": "Human-readable error description", "example": "One or more fields are invalid", "type": "string" }, "fields": { "description": "List of field names that are missing or invalid", "example": [ "title", "description" ], "type": "array", "items": { "type": "string" } }, "validationErrors": { "description": "Detailed validation error information for each invalid field", "example": { "invalidFields": { "title": { "type": "too_small", "message": "Title must be at least 3 characters long", "path": [ "title" ] }, "deadline": { "type": "invalid_date", "message": "Deadline must be a valid date in the future", "path": [ "deadline" ] } } }, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "get": { "operationId": "listOrganisations", "summary": "List organisations", "description": "Lists all organisations accessible to the authenticated user", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "Response containing an array of organisations", "type": "object", "properties": { "data": { "description": "Array of organisations", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "description": "Name of the organisation", "example": "Acme Corporation", "type": "string" }, "stripeCustomerId": { "description": "Stripe customer ID for billing", "example": "cus_1234567890", "type": "string" }, "homepageUrl": { "description": "URL to the organisation's homepage", "example": "https://acme.example.com", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "logoUrl": { "description": "URL to the organisation's logo", "example": "https://acme.example.com/logo.png", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "description": "Creation timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "accountType": { "description": "Account type", "example": "HOBBY", "$ref": "#/components/schemas/OrganisationAccountTypeEnum" }, "billingCycleStartDate": { "description": "The start date of the current billing cycle.", "example": "2025-03-26T22:35:46Z", "type": "string" }, "billingCycleFlexCreditAllowance": { "description": "Number of flex credits available at the start of the current billing cycle.", "example": 100000, "type": "number" }, "updatedAt": { "description": "Last update timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "status": { "description": "Status of the organisation", "example": "ACTIVE", "default": "ACTIVE", "type": "string", "enum": [ "ACTIVE", "ARCHIVED" ] }, "unprocessedFeedbackCount": { "$ref": "#/components/schemas/Organisation" } }, "required": [ "id", "name", "createdAt", "accountType", "billingCycleStartDate", "billingCycleFlexCreditAllowance", "updatedAt", "status", "unprocessedFeedbackCount" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/organisations/{orgId}": { "get": { "operationId": "getOrganisation", "summary": "Get organisation by ID", "description": "Retrieves a specific organisation by ID", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "Response containing a single organisation", "type": "object", "properties": { "data": { "description": "Organisation data", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "description": "Name of the organisation", "example": "Acme Corporation", "type": "string" }, "stripeCustomerId": { "description": "Stripe customer ID for billing", "example": "cus_1234567890", "type": "string" }, "homepageUrl": { "description": "URL to the organisation's homepage", "example": "https://acme.example.com", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "logoUrl": { "description": "URL to the organisation's logo", "example": "https://acme.example.com/logo.png", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "description": "Creation timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "accountType": { "description": "Account type", "example": "HOBBY", "$ref": "#/components/schemas/OrganisationAccountTypeEnum" }, "billingCycleStartDate": { "description": "The start date of the current billing cycle.", "example": "2025-03-26T22:35:46Z", "type": "string" }, "billingCycleFlexCreditAllowance": { "description": "Number of flex credits available at the start of the current billing cycle.", "example": 100000, "type": "number" }, "updatedAt": { "description": "Last update timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "status": { "description": "Status of the organisation", "example": "ACTIVE", "default": "ACTIVE", "type": "string", "enum": [ "ACTIVE", "ARCHIVED" ] }, "unprocessedFeedbackCount": { "$ref": "#/components/schemas/Organisation" } }, "required": [ "id", "name", "createdAt", "accountType", "billingCycleStartDate", "billingCycleFlexCreditAllowance", "updatedAt", "status", "unprocessedFeedbackCount" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Organisation not found", "content": { "application/json": { "schema": { "description": "Not Found - The requested resource does not exist", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "NOT_FOUND", "type": "string" }, "description": { "description": "Human-readable error description", "example": "The requested resource was not found", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "put": { "operationId": "updateOrganisation", "summary": "Update organisation", "description": "Updates a specific organisation by ID", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganisationPayload" } } } }, "responses": { "200": { "description": "Organisation updated successfully", "content": { "application/json": { "schema": { "description": "Response containing a single organisation", "type": "object", "properties": { "data": { "description": "Organisation data", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "description": "Name of the organisation", "example": "Acme Corporation", "type": "string" }, "stripeCustomerId": { "description": "Stripe customer ID for billing", "example": "cus_1234567890", "type": "string" }, "homepageUrl": { "description": "URL to the organisation's homepage", "example": "https://acme.example.com", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "logoUrl": { "description": "URL to the organisation's logo", "example": "https://acme.example.com/logo.png", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "description": "Creation timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "accountType": { "description": "Account type", "example": "HOBBY", "$ref": "#/components/schemas/OrganisationAccountTypeEnum" }, "billingCycleStartDate": { "description": "The start date of the current billing cycle.", "example": "2025-03-26T22:35:46Z", "type": "string" }, "billingCycleFlexCreditAllowance": { "description": "Number of flex credits available at the start of the current billing cycle.", "example": 100000, "type": "number" }, "updatedAt": { "description": "Last update timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "status": { "description": "Status of the organisation", "example": "ACTIVE", "default": "ACTIVE", "type": "string", "enum": [ "ACTIVE", "ARCHIVED" ] }, "unprocessedFeedbackCount": { "$ref": "#/components/schemas/Organisation" } }, "required": [ "id", "name", "createdAt", "accountType", "billingCycleStartDate", "billingCycleFlexCreditAllowance", "updatedAt", "status", "unprocessedFeedbackCount" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input parameters or missing required fields", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INVALID_REQUEST", "type": "string" }, "description": { "description": "Human-readable error description", "example": "One or more fields are invalid", "type": "string" }, "fields": { "description": "List of field names that are missing or invalid", "example": [ "title", "description" ], "type": "array", "items": { "type": "string" } }, "validationErrors": { "description": "Detailed validation error information for each invalid field", "example": { "invalidFields": { "title": { "type": "too_small", "message": "Title must be at least 3 characters long", "path": [ "title" ] }, "deadline": { "type": "invalid_date", "message": "Deadline must be a valid date in the future", "path": [ "deadline" ] } } }, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Organisation not found", "content": { "application/json": { "schema": { "description": "Not Found - The requested resource does not exist", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "NOT_FOUND", "type": "string" }, "description": { "description": "Human-readable error description", "example": "The requested resource was not found", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "delete": { "operationId": "deleteOrganisation", "summary": "Delete organisation", "description": "Deletes a specific organisation by ID", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" } ], "responses": { "200": { "description": "Organisation deleted successfully", "content": { "application/json": { "schema": { "description": "Response containing a success message", "type": "object", "properties": { "data": { "description": "Success message data", "type": "object", "properties": { "message": { "description": "Success message", "example": "Organisation deleted successfully", "type": "string" } }, "required": [ "message" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Organisation not found", "content": { "application/json": { "schema": { "description": "Not Found - The requested resource does not exist", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "NOT_FOUND", "type": "string" }, "description": { "description": "Human-readable error description", "example": "The requested resource was not found", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/v1/whoami": { "get": { "operationId": "whoAmI", "summary": "Retrieve authenticated user's organization and workspace information", "description": "Returns the ID and name of the authenticated user's organization and workspace. This is only callable by an API key which is workspace scoped.", "tags": [ "Squad" ], "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "Successfully retrieved user information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhoAmIResponse" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "500": { "description": "Internal server error" } } } }, "/v1/data-ingress": { "post": { "operationId": "processDataIngress", "summary": "Process insight for a workspace", "description": "Receives insight data and processes it for a specific workspace and organization", "tags": [ "Squad" ], "security": [ { "apiKeyAuth": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "text/plain": { "schema": { "description": "Raw insight content", "example": "I found the dashboard confusing to navigate", "type": "string" } } } }, "responses": { "201": { "description": "Insight processed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InsightResponse" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request (e.g., missing body or invalid parameters)" }, "500": { "description": "Internal server error" } } } }, "/v1/data-ingress/{feedbackSource}": { "post": { "operationId": "processDataIngressWithSource", "summary": "Process insight for a workspace", "description": "Receives insight data and processes it for a specific workspace and organization", "tags": [ "Squad" ], "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "feedbackSource", "schema": { "type": "string" }, "required": true, "description": "The source of the insight", "example": "typeform" } ], "requestBody": { "required": true, "content": { "text/plain": { "schema": { "description": "Raw insight content", "example": "I found the dashboard confusing to navigate", "type": "string" } } } }, "responses": { "201": { "description": "Insight processed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InsightResponse" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request (e.g., missing body or invalid parameters)" }, "500": { "description": "Internal server error" } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/data-ingress": { "post": { "operationId": "processWorkspaceDataIngress", "summary": "Process insight for a workspace", "description": "Receives insight data and processes it for a specific workspace and organization", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "requestBody": { "required": true, "content": { "text/plain": { "schema": { "description": "Raw insight content", "example": "I found the dashboard confusing to navigate", "type": "string" } } } }, "responses": { "201": { "description": "Insight processed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InsightResponse" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request (e.g., missing body or invalid parameters)" }, "500": { "description": "Internal server error" } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/data-ingress/{feedbackSource}": { "post": { "operationId": "processWorkspaceDataIngressWithSource", "summary": "Process insight for a workspace", "description": "Receives insight data and processes it for a specific workspace and organization", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "feedbackSource", "schema": { "type": "string" }, "required": true, "description": "The source of the insight", "example": "typeform" } ], "requestBody": { "required": true, "content": { "text/plain": { "schema": { "description": "Raw insight content", "example": "I found the dashboard confusing to navigate", "type": "string" } } } }, "responses": { "201": { "description": "Insight processed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InsightResponse" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request (e.g., missing body or invalid parameters)" }, "500": { "description": "Internal server error" } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/feedback-document": { "post": { "operationId": "uploadFeedbackDocument", "summary": "Upload feedback document", "description": "Uploads a document related to feedback for processing and analysis", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFeedbackDocumentPayload" } } } }, "responses": { "200": { "description": "Document uploaded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFeedbackDocumentResponse" } } } }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "413": { "description": "Payload Too Large - File size exceeds limits" }, "415": { "description": "Unsupported Media Type - File format not supported" }, "500": { "description": "Internal Server Error" } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/opportunities/{opportunityId}/generate-solutions": { "post": { "operationId": "generateSolutions", "summary": "Generate solutions for an opportunity", "description": "Asynchronously generates AI-powered solutions based on the insight associated with an opportunity", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "opportunityId", "schema": { "type": "string" }, "required": true, "description": "Opportunity ID", "example": "opp_12345" } ], "responses": { "202": { "description": "Solution generation process accepted and started asynchronously" }, "400": { "description": "Bad request - invalid input parameters" }, "401": { "description": "Unauthorized - invalid or missing authentication" }, "404": { "description": "Opportunity not found" }, "500": { "description": "Internal server error" } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/opportunities/{opportunityId}/insights/mark-all-seen": { "post": { "operationId": "markAllOpportunityInsightsSeen", "summary": "Mark all opportunity insights as seen", "description": "Marks all insight items associated with an opportunity as having been seen by the user", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "opportunityId", "schema": { "type": "string" }, "required": true, "description": "Opportunity ID", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4" } ], "responses": { "204": { "description": "All insight items successfully marked as seen" }, "400": { "description": "Bad request - invalid input parameters" }, "401": { "description": "Unauthorized - invalid or missing authentication" }, "404": { "description": "Opportunity not found" }, "500": { "description": "Internal server error" } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/opportunities/{opportunityId}/relationships/{action}": { "post": { "operationId": "manageOpportunityRelationships", "summary": "Manage opportunity relationships", "description": "Add or remove relationships between an opportunity and other entities (solutions, outcomes, or insight)", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "opportunityId", "schema": { "type": "string" }, "required": true, "description": "Opportunity ID", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4" }, { "in": "path", "name": "action", "schema": { "param": { "name": "action", "in": "path", "required": true, "description": "Action to perform on relationships", "example": "add" }, "$ref": "#/components/schemas/RelationshipAction" }, "required": true, "description": "Action to perform on relationships", "example": "add" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityRelationshipsPayload" } } } }, "responses": { "204": { "description": "Relationships successfully modified" }, "400": { "description": "Bad request - invalid input parameters" }, "401": { "description": "Unauthorized - invalid or missing authentication" }, "404": { "description": "Resource not found" }, "500": { "description": "Internal server error" } } } }, "/organisations/{orgId}/status": { "get": { "operationId": "getOrganisationStatus", "summary": "Get organization status", "description": "Retrieves the current status and subscription information of an organization", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" } ], "responses": { "200": { "description": "Organization status retrieved successfully", "content": { "application/json": { "schema": { "description": "Organization status response", "type": "object", "properties": { "data": { "description": "Organization status data", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "description": "Name of the organisation", "example": "Acme Corporation", "type": "string" }, "stripeCustomerId": { "description": "Stripe customer ID for billing", "example": "cus_1234567890", "type": "string" }, "homepageUrl": { "description": "URL to the organisation's homepage", "example": "https://acme.example.com", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "logoUrl": { "description": "URL to the organisation's logo", "example": "https://acme.example.com/logo.png", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "description": "Creation timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "accountType": { "description": "Account type", "example": "HOBBY", "$ref": "#/components/schemas/OrganisationAccountTypeEnum" }, "billingCycleStartDate": { "description": "The start date of the current billing cycle.", "example": "2025-03-26T22:35:46Z", "type": "string" }, "billingCycleFlexCreditAllowance": { "description": "Number of flex credits available at the start of the current billing cycle.", "example": 100000, "type": "number" }, "updatedAt": { "description": "Last update timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "status": { "description": "Status of the organisation", "example": "ACTIVE", "default": "ACTIVE", "type": "string", "enum": [ "ACTIVE", "ARCHIVED" ] }, "hasRemainingCredits": { "description": "Whether the organization has remaining credits", "example": true, "type": "boolean" }, "billingCycleCreditAllowance": { "description": "The number of credits available for the current billing cycle", "example": 250, "type": "number" }, "billingCycleCreditUsage": { "description": "The number of credits used in the current billing cycle so far", "example": 100, "type": "number" }, "billingCycleFlexCreditUsage": { "description": "The number of flex credits used in the current billing cycle so far", "example": 100, "type": "number" }, "currentBillingCycleStartDate": { "description": "The date the current billing cycle started", "example": "2025-06-24", "type": "string" }, "currentBillingCycleEndDate": { "description": "The date the current billing cycle will end", "example": "2025-06-24", "type": "string" }, "totalMembers": { "description": "The total number of members in the organization", "example": 10, "type": "number" } }, "required": [ "id", "name", "createdAt", "accountType", "billingCycleStartDate", "billingCycleFlexCreditAllowance", "updatedAt", "status", "hasRemainingCredits", "billingCycleCreditAllowance", "billingCycleCreditUsage", "billingCycleFlexCreditUsage", "currentBillingCycleStartDate", "currentBillingCycleEndDate", "totalMembers" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - invalid or missing authentication", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "description": "Not Found - The requested resource does not exist", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "NOT_FOUND", "type": "string" }, "description": { "description": "Human-readable error description", "example": "The requested resource was not found", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/outcomes/{outcomeId}/relationships/{action}": { "post": { "operationId": "manageOutcomeRelationships", "summary": "Manage outcome relationships", "description": "Add or remove relationships between an outcome and other entities (opportunities, metrics, solutions, or insight)", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "outcomeId", "schema": { "type": "string" }, "required": true, "description": "Outcome ID", "example": "7b9e5d2c-f314-48a9-be56-9843a2f6c019" }, { "in": "path", "name": "action", "schema": { "param": { "name": "action", "in": "path", "required": true, "description": "Action to perform on relationships", "example": "add" }, "$ref": "#/components/schemas/RelationshipAction" }, "required": true, "description": "Action to perform on relationships", "example": "add" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutcomeRelationshipsPayload" } } } }, "responses": { "204": { "description": "Relationships successfully modified" }, "400": { "description": "Bad request - invalid input parameters" }, "401": { "description": "Unauthorized - invalid or missing authentication" }, "404": { "description": "Resource not found" }, "500": { "description": "Internal server error" } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/solutions/{solutionId}/relationships/{action}": { "post": { "operationId": "manageSolutionRelationships", "summary": "Manage solution relationships", "description": "Add or remove relationships between a solution and other entities (opportunities, outcomes, or insight)", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "solutionId", "schema": { "type": "string" }, "required": true, "description": "Solution ID", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4" }, { "in": "path", "name": "action", "schema": { "param": { "name": "action", "in": "path", "required": true, "description": "Action to perform on relationships", "example": "add" }, "$ref": "#/components/schemas/RelationshipAction" }, "required": true, "description": "Action to perform on relationships", "example": "add" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SolutionRelationshipsPayload" } } } }, "responses": { "204": { "description": "Relationships successfully modified" }, "400": { "description": "Bad request - invalid input parameters" }, "401": { "description": "Unauthorized - invalid or missing authentication" }, "404": { "description": "Resource not found" }, "500": { "description": "Internal server error" } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/solutions/prioritise": { "post": { "operationId": "prioritiseSolutions", "summary": "Prioritise solutions", "description": "Reorders one or more solutions based on provided order", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrioritiseSolutionsRequest" } } } }, "responses": { "202": { "description": "Solution prioritization request accepted and queued for processing" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "409": { "description": "Conflict" } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/knowledge/source/url": { "post": { "operationId": "createKnowledgeFromUrl", "summary": "Create a new piece of knowledge from a URL", "description": "Fetches content from the provided URL and creates a new piece of knowledge", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKnowledgeFromUrlPayload" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SingleKnowledgeResponse" } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input parameters or missing required fields", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INVALID_REQUEST", "type": "string" }, "description": { "description": "Human-readable error description", "example": "One or more fields are invalid", "type": "string" }, "fields": { "description": "List of field names that are missing or invalid", "example": [ "title", "description" ], "type": "array", "items": { "type": "string" } }, "validationErrors": { "description": "Detailed validation error information for each invalid field", "example": { "invalidFields": { "title": { "type": "too_small", "message": "Title must be at least 3 characters long", "path": [ "title" ] }, "deadline": { "type": "invalid_date", "message": "Deadline must be a valid date in the future", "path": [ "deadline" ] } } }, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/knowledge/source/pdf": { "post": { "operationId": "createKnowledgeFromPdf", "summary": "Create a new piece of knowledge from a PDF file", "description": "Extracts content from the provided PDF file and creates a new piece of knowledge", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKnowledgeFromPdfPayload" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SingleKnowledgeResponseWithUploadPdf" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input parameters or missing required fields", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INVALID_REQUEST", "type": "string" }, "description": { "description": "Human-readable error description", "example": "One or more fields are invalid", "type": "string" }, "fields": { "description": "List of field names that are missing or invalid", "example": [ "title", "description" ], "type": "array", "items": { "type": "string" } }, "validationErrors": { "description": "Detailed validation error information for each invalid field", "example": { "invalidFields": { "title": { "type": "too_small", "message": "Title must be at least 3 characters long", "path": [ "title" ] }, "deadline": { "type": "invalid_date", "message": "Deadline must be a valid date in the future", "path": [ "deadline" ] } } }, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/knowledge": { "post": { "operationId": "createKnowledge", "summary": "Create a new piece of knowledge", "description": "Creates a new piece of knowledge from provided text content", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKnowledgePayload" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SingleKnowledgeResponse" } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input parameters or missing required fields", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INVALID_REQUEST", "type": "string" }, "description": { "description": "Human-readable error description", "example": "One or more fields are invalid", "type": "string" }, "fields": { "description": "List of field names that are missing or invalid", "example": [ "title", "description" ], "type": "array", "items": { "type": "string" } }, "validationErrors": { "description": "Detailed validation error information for each invalid field", "example": { "invalidFields": { "title": { "type": "too_small", "message": "Title must be at least 3 characters long", "path": [ "title" ] }, "deadline": { "type": "invalid_date", "message": "Deadline must be a valid date in the future", "path": [ "deadline" ] } } }, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "get": { "operationId": "listKnowledge", "description": "Retrieves a list of all pieces of knowledge", "summary": "List all pieces of knowledge", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeArrayResponse" } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/knowledge/{knowledgeId}": { "get": { "operationId": "getKnowledge", "summary": "Get a piece of knowledge by ID", "description": "Retrieves a specific piece of knowledge by its ID", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "knowledgeId", "schema": { "type": "string" }, "required": true, "description": "Knowledge ID", "example": "7b9e5d2c-f314-48a9-be56-9843a2f6c019" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SingleKnowledgeResponse" } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input parameters or missing required fields", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INVALID_REQUEST", "type": "string" }, "description": { "description": "Human-readable error description", "example": "One or more fields are invalid", "type": "string" }, "fields": { "description": "List of field names that are missing or invalid", "example": [ "title", "description" ], "type": "array", "items": { "type": "string" } }, "validationErrors": { "description": "Detailed validation error information for each invalid field", "example": { "invalidFields": { "title": { "type": "too_small", "message": "Title must be at least 3 characters long", "path": [ "title" ] }, "deadline": { "type": "invalid_date", "message": "Deadline must be a valid date in the future", "path": [ "deadline" ] } } }, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Not Found - Knowledge does not exist", "content": { "application/json": { "schema": { "description": "Not Found - The requested resource does not exist", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "NOT_FOUND", "type": "string" }, "description": { "description": "Human-readable error description", "example": "The requested resource was not found", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "put": { "operationId": "updateKnowledge", "summary": "Update a piece of knowledge", "description": "Updates the title, description, or content of an existing piece of knowledge", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "knowledgeId", "schema": { "type": "string" }, "required": true, "description": "Knowledge ID", "example": "7b9e5d2c-f314-48a9-be56-9843a2f6c019" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateKnowledgePayload" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SingleKnowledgeResponse" } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input parameters or missing required fields", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INVALID_REQUEST", "type": "string" }, "description": { "description": "Human-readable error description", "example": "One or more fields are invalid", "type": "string" }, "fields": { "description": "List of field names that are missing or invalid", "example": [ "title", "description" ], "type": "array", "items": { "type": "string" } }, "validationErrors": { "description": "Detailed validation error information for each invalid field", "example": { "invalidFields": { "title": { "type": "too_small", "message": "Title must be at least 3 characters long", "path": [ "title" ] }, "deadline": { "type": "invalid_date", "message": "Deadline must be a valid date in the future", "path": [ "deadline" ] } } }, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Not Found - Knowledge does not exist", "content": { "application/json": { "schema": { "description": "Not Found - The requested resource does not exist", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "NOT_FOUND", "type": "string" }, "description": { "description": "Human-readable error description", "example": "The requested resource was not found", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "delete": { "operationId": "deleteKnowledge", "summary": "Delete a piece of knowledge", "description": "Deletes a specific piece of knowledge by its ID", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "path", "name": "knowledgeId", "schema": { "type": "string" }, "required": true, "description": "Knowledge ID", "example": "7b9e5d2c-f314-48a9-be56-9843a2f6c019" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "Response containing a success message", "type": "object", "properties": { "data": { "description": "Success message data", "type": "object", "properties": { "message": { "description": "Success message", "example": "Knowledge deleted successfully", "type": "string" } }, "required": [ "message" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Not Found - Knowledge does not exist", "content": { "application/json": { "schema": { "description": "Not Found - The requested resource does not exist", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "NOT_FOUND", "type": "string" }, "description": { "description": "Human-readable error description", "example": "The requested resource was not found", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/test-proxy": { "post": { "operationId": "processTextProxy", "summary": "Process text through AI proxy", "description": "Processes a text prompt through an AI model and returns the result", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Request body for text proxy processing", "type": "object", "properties": { "prompt": { "description": "Text prompt to process", "example": "Analyze customer insight regarding our mobile app", "type": "string" }, "model": { "description": "AI model to use for processing", "example": "gpt-4", "type": "string" }, "options": { "type": "object", "properties": { "temperature": { "description": "Temperature parameter for the model", "example": 0.7, "type": "number" }, "maxTokens": { "description": "Maximum number of tokens in the response", "example": 500, "type": "number" } } } }, "required": [ "prompt" ] } } } }, "responses": { "200": { "description": "Successfully processed text", "content": { "application/json": { "schema": { "description": "Text proxy processing result", "type": "object", "properties": { "data": { "type": "object", "properties": { "result": { "description": "Processed text result", "example": "Based on the customer insight analysis...", "type": "string" }, "model": { "description": "AI model used for processing", "example": "gpt-4", "type": "string" }, "processingTime": { "description": "Time taken to process the request in milliseconds", "example": 1250, "type": "number" } }, "required": [ "result", "model", "processingTime" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad request - invalid input parameters" }, "401": { "description": "Unauthorized - invalid or missing authentication" }, "500": { "description": "Internal server error" } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/token-usage": { "post": { "operationId": "trackTokenUsage", "summary": "Track token usage", "description": "Tracks token usage for a given request", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "description": "Source of the token usage", "example": "in-app-chat", "type": "string" }, "inputTokens": { "description": "Number of input tokens", "example": 123, "type": "number" }, "outputTokens": { "description": "Number of output tokens", "example": 456, "type": "number" }, "thinking": { "description": "Whether the request is using thinking mode", "example": false, "type": "boolean" } }, "required": [ "source", "inputTokens", "outputTokens", "thinking" ] } } } }, "responses": { "201": { "description": "Token usage tracked successfully" }, "400": { "description": "Bad Request - Invalid input" }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/strategy-document": { "get": { "operationId": "getStrategyDocument", "summary": "Get strategy document", "description": "Retrieves the strategy document for the specified workspace", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" }, { "in": "query", "name": "include", "schema": { "description": "Comma-separated list of additional fields to include. Available options: solution.owner", "example": "solution.owner", "type": "string" }, "description": "Comma-separated list of additional fields to include. Available options: solution.owner" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateStrategyDocumentPayload" } } } }, "401": { "description": "Unauthorized - Authentication required" }, "403": { "description": "Forbidden - Insufficient permissions" } } } }, "/organisations/{orgId}/workspaces/{workspaceId}/similarity-search": { "post": { "operationId": "similaritySearch", "summary": "Find similar entities", "description": "Finds similar entities to the given query", "tags": [ "Squad" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "in": "path", "name": "orgId", "schema": { "type": "string" }, "required": true, "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184" }, { "in": "path", "name": "workspaceId", "schema": { "type": "string" }, "required": true, "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "description": "Query string", "example": "Number of tokens used", "type": "string" }, "filters": { "description": "List of Pinecone sources to search over", "example": [ "knowledge-base", "insights", "opportunities", "solutions" ], "type": "array", "items": { "type": "string", "enum": [ "knowledge-base", "insights", "opportunities", "solutions" ] } } }, "required": [ "query", "filters" ] } } } }, "responses": { "200": { "description": "Similarity search completed successfully", "content": { "application/json": { "schema": { "description": "Response containing a similarity search result", "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SimilaritySearchResponse" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Bad Request - Invalid input", "content": { "application/json": { "schema": { "description": "Bad Request - Invalid input parameters or missing required fields", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INVALID_REQUEST", "type": "string" }, "description": { "description": "Human-readable error description", "example": "One or more fields are invalid", "type": "string" }, "fields": { "description": "List of field names that are missing or invalid", "example": [ "title", "description" ], "type": "array", "items": { "type": "string" } }, "validationErrors": { "description": "Detailed validation error information for each invalid field", "example": { "invalidFields": { "title": { "type": "too_small", "message": "Title must be at least 3 characters long", "path": [ "title" ] }, "deadline": { "type": "invalid_date", "message": "Deadline must be a valid date in the future", "path": [ "deadline" ] } } }, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "description": "Unauthorized - Missing or invalid authentication token", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthenticated", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "description": "Forbidden - Insufficient permissions to access this resource", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "UNAUTHORISED_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "User is unauthorised", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "description": "Internal Server Error - An unexpected error occurred on the server", "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code identifier", "example": "INTERNAL_SERVER_ERROR", "type": "string" }, "description": { "description": "Human-readable error description", "example": "An unexpected error occurred on the server", "type": "string" } }, "required": [ "code", "description" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } } }, "components": { "schemas": { "CreateOutcomePayload": { "description": "Request schema for creating an outcome", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "description": "Title of the outcome", "example": "Increase User Engagement", "type": "string" }, "description": { "description": "Detailed description of the outcome", "example": "We aim to increase daily active users by 25% in Q3", "type": "string" }, "priority": { "description": "Priority level of the outcome", "example": 1, "type": "number" }, "trend": { "description": "Trend indicator for the outcome", "example": 0, "type": "number" }, "analyticEvents": { "description": "List of analytic events associated with the outcome", "example": [ "event1", "event2" ], "type": "array", "items": { "type": "string" } }, "ownerId": { "description": "ID of the owner of the outcome", "example": "7b9e5d2c-f314-48a9-be56-9843a2f6c019", "type": "string" }, "opportunityIds": { "type": "array", "items": { "type": "string" } }, "metricIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "title", "description", "priority" ] }, "UpdateOutcomePayload": { "description": "Request schema for updating an outcome", "type": "object", "properties": { "title": { "description": "Title of the outcome", "example": "Increase User Engagement", "type": "string" }, "description": { "description": "Detailed description of the outcome", "example": "We aim to increase daily active users by 25% in Q3", "type": "string" }, "priority": { "description": "Priority level of the outcome", "example": 1, "type": "number" }, "trend": { "description": "Trend indicator for the outcome", "example": 0, "type": "number" }, "analyticEvents": { "description": "List of analytic events associated with the outcome", "example": [ "event1", "event2" ], "type": "array", "items": { "type": "string" } }, "ownerId": { "description": "ID of the owner of the outcome", "example": "7b9e5d2c-f314-48a9-be56-9843a2f6c019", "type": "string" }, "opportunityIds": { "type": "array", "items": { "type": "string" } }, "metricIds": { "type": "array", "items": { "type": "string" } } } }, "CreateMetricPayload": { "description": "Request schema for creating a metric", "type": "object", "properties": { "title": { "description": "Display name for the metric", "example": "Daily Active Users", "type": "string" }, "description": { "description": "Detailed description of the metric", "example": "Number of unique users who performed any action in the last 24 hours", "type": "string" }, "unit": { "description": "Unit of measurement for the metric", "example": "users", "type": "string" }, "type": { "description": "Category/type of the metric", "default": "custom", "type": "string", "enum": [ "engagement", "conversion", "revenue", "nps", "csat", "ces", "ratio", "custom" ] }, "targetOperator": { "description": "Comparison operator for the target", "type": "string", "enum": [ "greater_than", "less_than", "equal_to" ] }, "targetValue": { "description": "Target value to achieve", "example": 100, "type": "number" }, "targetDirection": { "description": "Direction of improvement (up = higher is better, down = lower is better)", "default": "up", "type": "string", "enum": [ "up", "down" ] }, "currentValue": { "description": "Current value of the metric", "example": 150, "type": "number" }, "previousValue": { "description": "Previous value of the metric for comparison", "example": 140, "type": "number" }, "periodType": { "description": "Type of period for metric comparison", "example": "calendar", "type": "string", "enum": [ "rolling", "calendar" ] }, "periodValue": { "description": "Specific period value for metric comparison", "example": "month", "type": "string", "enum": [ "day", "week", "month", "quarter", "year", "7-day", "30-day", "90-day" ] }, "timeseries": { "description": "Historical values for trend analysis", "type": "array", "items": { "$ref": "#/components/schemas/MetricTimeseriesPoint" } }, "relatedOutcomes": { "description": "Related outcomes that use this metric", "type": "array", "items": {} }, "id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "string", "const": "" } ] }, "outcomeIds": { "description": "Array of outcome IDs to associate with this metric", "example": [ "7b9e5d2c-f314-48a9-be56-9843a2f6c019" ], "type": "array", "items": { "type": "string" } }, "ownerId": { "type": "string" } }, "required": [ "title", "ownerId" ] }, "MetricTimeseriesPoint": { "description": "A single data point in a metric's time series", "type": "object", "properties": { "date": { "description": "ISO datetime string for the data point", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "value": { "description": "Metric value at this point in time", "example": 85, "type": "number" } }, "required": [ "date", "value" ] }, "UpdateMetricPayload": { "description": "Request schema for updating an metric", "type": "object", "properties": { "title": { "description": "Display name for the metric", "example": "Daily Active Users", "type": "string" }, "description": { "description": "Detailed description of the metric", "example": "Number of unique users who performed any action in the last 24 hours", "type": "string" }, "unit": { "description": "Unit of measurement for the metric", "example": "users", "type": "string" }, "type": { "description": "Category/type of the metric", "default": "custom", "type": "string", "enum": [ "engagement", "conversion", "revenue", "nps", "csat", "ces", "ratio", "custom" ] }, "targetOperator": { "description": "Comparison operator for the target", "type": "string", "enum": [ "greater_than", "less_than", "equal_to" ] }, "targetValue": { "description": "Target value to achieve", "example": 100, "type": "number" }, "targetDirection": { "description": "Direction of improvement (up = higher is better, down = lower is better)", "default": "up", "type": "string", "enum": [ "up", "down" ] }, "currentValue": { "description": "Current value of the metric", "example": 150, "type": "number" }, "previousValue": { "description": "Previous value of the metric for comparison", "example": 140, "type": "number" }, "periodType": { "description": "Type of period for metric comparison", "example": "calendar", "type": "string", "enum": [ "rolling", "calendar" ] }, "periodValue": { "description": "Specific period value for metric comparison", "example": "month", "type": "string", "enum": [ "day", "week", "month", "quarter", "year", "7-day", "30-day", "90-day" ] }, "ownerId": { "description": "UserId of the Owner/responsible person for this metric", "example": "user_123456789", "type": "string" }, "timeseries": { "description": "Historical values for trend analysis", "type": "array", "items": { "$ref": "#/components/schemas/MetricTimeseriesPoint" } }, "relatedOutcomes": { "description": "Related outcomes that use this metric", "type": "array", "items": {} }, "outcomeIds": { "description": "Array of outcome IDs to associate with this metric", "example": [ "7b9e5d2c-f314-48a9-be56-9843a2f6c019" ], "type": "array", "items": { "type": "string" } } } }, "RelationshipAction": { "type": "string", "enum": [ "add", "remove" ] }, "MetricRelationshipsPayload": { "description": "Request body for managing metric relationships", "type": "object", "properties": { "outcomeIds": { "description": "Array of outcome IDs to associate with the metric", "example": [ "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d" ], "type": "array", "items": { "type": "string" } } } }, "OnboardingPayload": { "description": "Request schema for onboarding", "type": "object", "properties": { "name": { "description": "Name of the organization to create", "example": "Acme Corporation", "type": "string", "minLength": 1 }, "description": { "description": "Description of the organization for generating workspace and outcomes", "example": "A technology company focused on AI solutions for enterprise customers", "type": "string", "minLength": 1 } }, "required": [ "name", "description" ] }, "OnboardingUpdatePayload": { "description": "Request schema for updating onboarding", "$ref": "#/components/schemas/OnboardingPayload" }, "OnboardingV2Payload": { "description": "Request schema for one-shot onboarding", "type": "object", "properties": { "text": { "description": "Text input describing the business or product", "example": "A technology company focused on AI solutions for enterprise customers", "type": "string", "minLength": 1 }, "knowledgeIds": { "description": "Array of knowledge entity IDs to process", "example": [ "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184", "b7e2d5a9-3c18-4e6f-9a42-f8d1c7b5e3a2" ], "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "newProduct": { "description": "Flag indicating if this is a new product (optional)", "example": true, "default": false, "type": "boolean" } }, "required": [ "text", "knowledgeIds" ] }, "CreateFeedbackRequest": { "description": "Request schema for creating feedback", "type": "object", "properties": { "content": { "description": "Original raw feedback content", "example": "I found the dashboard charts difficult to understand at first glance. The colors are confusing and the data is hard to interpret.", "type": "string" }, "source": { "description": "Source of the feedback", "example": "Customer Interview", "type": "string" }, "sentimentScore": { "description": "Sentiment score from -1 (negative) to 1 (positive)", "example": 0.75, "type": "number", "minimum": -1, "maximum": 1 }, "sentimentCategory": { "description": "Sentiment classification category", "example": "Positive", "type": "string", "enum": [ "Positive", "Neutral", "Negative" ] }, "sentimentConfidence": { "description": "Confidence in sentiment analysis (0-1)", "example": 0.95, "type": "number", "minimum": 0, "maximum": 1 }, "createdAtEpoch": { "description": "Unix epoch timestamp for efficient Neo4j queries", "example": 1679867746, "type": "number" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "content", "source" ] }, "CreateIntegrationPayload": { "description": "Request schema for creating an integration", "type": "object", "properties": { "integrationId": { "type": "string", "minLength": 1 }, "config": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "integrationId", "config" ] }, "UpdateIntegrationPayload": { "description": "Request schema for updating an integration", "type": "object", "properties": { "config": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "config" ] }, "CreateOpportunityPayload": { "description": "Request schema for creating an opportunity", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "description": "Title of the opportunity", "example": "Improve Customer Onboarding Experience", "type": "string" }, "description": { "description": "Description of the opportunity", "example": "Streamline the initial user setup process to reduce drop-offs", "type": "string" }, "createdBy": { "description": "How the opportunity was created", "example": "user", "type": "string", "enum": [ "user", "generated" ] }, "ownerId": { "description": "ID of the opportunity owner", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4", "type": "string" }, "solutionIds": { "type": "array", "items": { "type": "string" } }, "insightIds": { "type": "array", "items": { "type": "string" } }, "outcomeIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "title", "description", "createdBy" ] }, "UpdateOpportunityPayload": { "description": "Request schema for updating an opportunity", "type": "object", "properties": { "read": { "description": "Whether the opportunity has been read", "example": false, "type": "boolean" }, "status": { "description": "Current status of the opportunity", "example": "New", "type": "string", "enum": [ "New", "Solved", "Planned", "InProgress" ] }, "title": { "description": "Title of the opportunity", "example": "Improve Customer Onboarding Experience", "type": "string" }, "description": { "description": "Description of the opportunity", "example": "Streamline the initial user setup process to reduce drop-offs", "type": "string" }, "solutionsGeneratingState": { "description": "Current state of solution generation", "example": "initial", "type": "string", "enum": [ "generating", "generated", "initial", "error" ] }, "createdBy": { "description": "How the opportunity was created", "example": "user", "type": "string", "enum": [ "user", "generated" ] }, "ownerId": { "description": "ID of the opportunity owner", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4", "type": "string" }, "insightIds": { "type": "array", "items": { "type": "string" } }, "outcomeIds": { "type": "array", "items": { "type": "string" } }, "solutionIds": { "type": "array", "items": { "type": "string" } }, "topicIds": { "type": "array", "items": { "type": "string" } } } }, "CreateSolutionPayload": { "description": "Request schema for creating a solution", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "systemPrompt": { "type": "string" }, "aiProcessingState": { "type": "string", "enum": [ "INITIAL", "PROCESSING", "FINISHED", "ERROR" ] }, "refinementLog": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" } }, "required": [ "id", "role", "content" ] } }, "title": { "description": "Title of the solution", "example": "Implement Single Sign-On", "type": "string" }, "description": { "description": "Description of the solution", "example": "Integrate with OAuth providers to simplify user login experience", "type": "string" }, "status": { "description": "Solution status", "example": "Backlog", "type": "string", "enum": [ "Backlog", "New", "Planned", "InDevelopment", "Complete", "Cancelled", "Live" ] }, "pros": { "type": "array", "items": { "type": "string" } }, "cons": { "type": "array", "items": { "type": "string" } }, "createdBy": { "description": "How the solution was created", "example": "generated", "type": "string", "enum": [ "user", "generated" ] }, "ownerId": { "type": "string" }, "prd": { "description": "Product Requirements Document content for the solution", "example": "Objective: Help users easily create...", "type": "string" }, "opportunityIds": { "type": "array", "items": { "type": "string" } }, "horizon": { "description": "Solution horizon", "example": "now", "type": "string", "enum": [ "now", "next", "later" ] } }, "required": [ "title", "description", "createdBy", "prd" ] }, "UpdateSolutionPayload": { "description": "Request schema for updating a solution", "type": "object", "properties": { "systemPrompt": { "description": "System prompt used to generate the requirement", "example": "Hello", "type": "string" }, "aiProcessingState": { "description": "Current state of AI processing", "example": "FINISHED", "type": "string", "enum": [ "INITIAL", "PROCESSING", "FINISHED", "ERROR" ] }, "refinementLog": { "description": "Log of refinements made to the requirement", "example": [], "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique identifier for the log entry", "example": "96dafa28-1e01-4ba4-a92b-babb8b792823", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "role": { "description": "Role of the entity making the log entry", "example": "assistant", "type": "string", "enum": [ "user", "assistant" ] }, "content": { "description": "Content of the log entry", "example": "Initial requirement", "type": "string" } }, "required": [ "id", "role", "content" ] } }, "title": { "description": "Title of the solution", "example": "Implement Single Sign-On", "type": "string" }, "description": { "description": "Description of the solution", "example": "Integrate with OAuth providers to simplify user login experience", "type": "string" }, "status": { "description": "Solution status", "example": "Backlog", "type": "string", "enum": [ "Backlog", "New", "Planned", "InDevelopment", "Complete", "Cancelled", "Live" ] }, "pros": { "description": "List of pros/advantages for this solution", "example": [ "Improved security", "Simplified login flow", "Reduced password reset requests" ], "type": "array", "items": { "type": "string" } }, "cons": { "description": "List of cons/disadvantages for this solution", "example": [ "Requires integration with external providers", "May add complexity to registration" ], "type": "array", "items": { "type": "string" } }, "ownerId": { "description": "ID of the solution owner", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4", "type": "string" }, "prd": { "description": "Product Requirements Document content for the solution", "example": "Objective: Help users easily create...", "type": "string" }, "horizon": { "description": "Time horizon for the solution", "example": "now", "type": "string", "enum": [ "now", "next", "later" ] }, "opportunityIds": { "type": "array", "items": { "type": "string" } }, "updateTriggeredBy": { "description": "Who triggered the update. If not provided, defaults to 'user'", "example": "user", "type": "string", "enum": [ "user", "AI" ] } } }, "CreateTopicPayload": { "description": "Request schema for creating a topic", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "description": "Title of the topic", "example": "User Interface Improvements", "type": "string" }, "description": { "description": "Description of the topic", "example": "General insight related to UI/UX improvements", "type": "string" }, "opportunityIds": { "description": "List of opportunity IDs associated with the topic", "example": [ "d4e71c2b-a498-42af-b7f5-69de06a0d7c4" ], "type": "array", "items": { "type": "string" } }, "insightIds": { "description": "List of insight IDs associated with the topic", "example": [ "d4e71c2b-a498-42af-b7f5-69de06a0d7c4" ], "type": "array", "items": { "type": "string" } } }, "required": [ "title", "description" ] }, "UpdateTopicPayload": { "description": "Request schema for updating a topic", "type": "object", "properties": { "title": { "description": "Title of the topic", "example": "User Interface Improvements", "type": "string" }, "description": { "description": "Description of the topic", "example": "General insight related to UI/UX improvements", "type": "string" }, "opportunityIds": { "description": "List of opportunity IDs associated with the topic", "example": [ "d4e71c2b-a498-42af-b7f5-69de06a0d7c4" ], "type": "array", "items": { "type": "string" } }, "insightIds": { "description": "List of insight IDs associated with the topic", "example": [ "d4e71c2b-a498-42af-b7f5-69de06a0d7c4" ], "type": "array", "items": { "type": "string" } } } }, "CreateWorkspacePayload": { "description": "Request schema for creating a workspace", "type": "object", "properties": { "name": { "type": "string" }, "homepageUrl": { "type": "string" }, "logoUrl": { "type": "string" }, "missionStatement": { "description": "Mission statement for the workspace", "example": "Develop innovative products that solve real customer problems", "type": "string" }, "description": { "type": "string" }, "outcomes": { "type": "array", "items": { "type": "string" } }, "utm": { "type": "object", "properties": { "source": { "type": "string" }, "medium": { "type": "string" }, "campaign": { "type": "string" }, "term": { "type": "string" }, "content": { "type": "string" } } } }, "required": [ "name", "missionStatement" ] }, "UpdateWorkspacePayload": { "description": "Request schema for updating a workspace", "type": "object", "properties": { "name": { "description": "Name of the workspace", "example": "Product Development", "type": "string" }, "homepageUrl": { "description": "URL to the workspace's homepage", "example": "https://product.example.com", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "logoUrl": { "description": "URL to the workspace's logo", "example": "https://product.example.com/logo.png", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "missionStatement": { "description": "Mission statement for the workspace", "example": "Develop innovative products that solve real customer problems", "type": "string" }, "description": { "description": "Detailed description of the workspace", "example": "This workspace focuses on our core product development initiatives, including roadmap planning, feature development, and product improvements.", "type": "string" }, "status": { "description": "Status of the workspace", "example": "Initializing", "type": "string", "enum": [ "Initializing", "OnboardingDeepResearch", "OnboardingConsiderWorkspace", "OnboardingConsiderOpportunities", "OnboardingConsiderOpportunitiesToOutcomes", "OnboardingConsiderSolutionGeneration", "OnboardingConsiderSolutionsToBuild", "OnboardingSelectSolutionsToBuild", "OnboardingMapSolutionsToRoadmap", "Active", "Inactive" ] } } }, "CreateOrganisationPayload": { "description": "Request schema for creating an organisation", "type": "object", "properties": { "name": { "description": "Name of the organisation", "example": "Acme Corporation", "type": "string" }, "homepageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "homepageUrl", "logoUrl" ] }, "UpdateOrganisationPayload": { "description": "Request schema for updating an organisation", "type": "object", "properties": { "name": { "description": "Name of the organisation", "example": "Acme Corporation", "type": "string" }, "homepageUrl": { "description": "URL to the organisation's homepage", "example": "https://acme.example.com", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "logoUrl": { "description": "URL to the organisation's logo", "example": "https://acme.example.com/logo.png", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accountType": { "$ref": "#/components/schemas/OrganisationAccountTypeEnum" }, "billingCycleStartDate": { "description": "The start date of the current billing cycle.", "example": "2025-03-26T22:35:46Z", "type": "string" }, "billingCycleFlexCreditAllowance": { "description": "Number of flex credits available at the start of the current billing cycle.", "example": 100000, "type": "number" }, "status": { "type": "string", "enum": [ "ACTIVE", "ARCHIVED" ] } } }, "OrganisationAccountTypeEnum": { "type": "string", "enum": [ "HOBBY", "PROFESSIONAL", "TEAM" ] }, "CreateFeedbackDocumentPayload": { "description": "Feedback document upload request", "type": "object", "properties": { "fileName": { "description": "Name of the document to upload", "example": "report.pdf", "type": "string" }, "source": { "description": "Source of the document", "example": "interview", "type": "string" } }, "required": [ "fileName" ] }, "OpportunityRelationshipsPayload": { "description": "Request body for managing opportunity relationships", "type": "object", "properties": { "solutionIds": { "description": "Array of solution IDs to associate with the opportunity", "example": [ "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d" ], "type": "array", "items": { "type": "string" } }, "outcomeIds": { "description": "Array of outcome IDs to associate with the opportunity", "example": [ "f6e5d4c3-b2a1-4b5a-9c8d-1e0f2a3b4c5d" ], "type": "array", "items": { "type": "string" } }, "insightIds": { "description": "Array of insight IDs to associate with the opportunity", "example": [ "c5d4e3f2-a1b2-4c5d-8e9f-0a1b2c3d4e5f" ], "type": "array", "items": { "type": "string" } } } }, "OutcomeRelationshipsPayload": { "description": "Request body for managing outcome relationships", "type": "object", "properties": { "opportunityIds": { "description": "Array of opportunity IDs to associate with the outcome", "example": [ "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d" ], "type": "array", "items": { "type": "string" } }, "metricIds": { "description": "Array of metric IDs to associate with the outcome", "example": [ "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d" ], "type": "array", "items": { "type": "string" } } } }, "SolutionRelationshipsPayload": { "description": "Request body for managing solution relationships", "type": "object", "properties": { "opportunityIds": { "description": "Array of opportunity IDs to associate with the solution", "example": [ "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d" ], "type": "array", "items": { "type": "string" } } } }, "PrioritiseSolutionsRequest": { "description": "Request schema for prioritising solutions", "example": { "beforeId": "e3f2c1b4-7a8d-5e4f-b8c7-7a8c9d1e2f3a", "solutionIds": [ "d4e71c2b-a498-42af-b7f5-69de06a0d7c4", "b5f2a0f4-6a7d-4a1f-9e6b-6bcb9c22d7c4", "c0e195d9-b918-4a3a-bd8b-f730361d044e" ] }, "type": "object", "properties": { "beforeId": { "description": "ID of solution before which to place the solutions, or null to place at the end", "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "solutionIds": { "description": "List of solution IDs to move", "minItems": 1, "type": "array", "items": { "type": "string" } }, "triggeredBy": { "description": "Who triggered the priority update. If not provided, defaults to 'user'", "type": "string", "enum": [ "user", "AI" ] } }, "required": [ "beforeId", "solutionIds" ] }, "CreateKnowledgeFromUrlPayload": { "description": "Request schema for creating knowledge from a URL", "type": "object", "properties": { "url": { "description": "The URL the user wishes to create knowledge from", "example": "https://example.com", "type": "string", "format": "uri" } }, "required": [ "url" ] }, "CreateKnowledgeFromPdfPayload": { "description": "Request schema for creating knowledge from a PDF file", "type": "object", "properties": { "fileName": { "description": "The name of the file to create knowledge from", "example": "example.pdf", "type": "string" } }, "required": [ "fileName" ] }, "CreateKnowledgePayload": { "description": "Request schema for creating knowledge", "type": "object", "properties": { "id": { "description": "An optional Knowledge ID must be a uuid", "example": "7b9e5d2c-f314-48a9-be56-9843a2f6c019", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "description": "Knowledge title", "example": "Best practices for AI in healthcare", "type": "string" }, "description": { "description": "Knowledge description - a short summary of the knowledge", "example": "A collection of best practices for AI in healthcare", "type": "string" }, "content": { "description": "Knowledge content - the full content of the knowledge", "example": "A collection of best practices for AI in healthcare", "type": "string" } }, "required": [ "title", "description", "content" ] }, "UpdateKnowledgePayload": { "description": "Request schema for updating knowledge", "type": "object", "properties": { "title": { "description": "Knowledge title", "example": "Best practices for AI in healthcare", "type": "string" }, "description": { "description": "Knowledge description - a short summary of the knowledge", "example": "A collection of best practices for AI in healthcare", "type": "string" }, "content": { "description": "The content of the knowledge, only available for text sources, optional", "example": "A collection of best practices for AI in healthcare", "type": "string" } } }, "OutcomeWithRelationships": { "description": "Outcome with relationships", "type": "object", "properties": { "id": { "description": "Unique identifier for the outcome", "example": "7b9e5d2c-f314-48a9-be56-9843a2f6c019", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "description": "Title of the outcome", "example": "Increase User Engagement", "type": "string" }, "description": { "description": "Detailed description of the outcome", "example": "We aim to increase daily active users by 25% in Q3", "type": "string" }, "priority": { "description": "Priority level of the outcome", "example": 1, "type": "number" }, "trend": { "description": "Trend indicator for the outcome", "example": 0, "type": "number" }, "analyticEvents": { "description": "List of analytic events associated with the outcome", "example": [ "event1", "event2" ], "type": "array", "items": { "type": "string" } }, "hideContent": { "description": "Whether the outcome is hidden", "example": false, "type": "boolean" }, "ownerId": { "description": "ID of the owner of the outcome", "example": "7b9e5d2c-f314-48a9-be56-9843a2f6c019", "type": "string" }, "createdAt": { "description": "Timestamp of when the outcome was created", "example": "2023-01-01T00:00:00.000Z", "type": "string" }, "updatedAt": { "description": "Timestamp of when the outcome was last updated", "example": "2023-01-01T00:00:00.000Z", "type": "string" }, "opportunities": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Opportunity" } }, "solutions": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Solution" } }, "insights": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Insight" } }, "metrics": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Metric" } } }, "required": [ "id", "title", "description", "priority", "hideContent", "createdAt", "updatedAt", "opportunities", "solutions", "insights", "metrics" ], "additionalProperties": false }, "Opportunity": { "description": "Opportunity data for a business", "type": "object", "properties": { "id": { "description": "Unique identifier for the opportunity", "example": "f5d8df32-60b4-417a-8b83-8d4dcb4e88e1", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "read": { "description": "Whether the opportunity has been read", "example": false, "type": "boolean" }, "status": { "description": "Current status of the opportunity", "example": "New", "type": "string", "enum": [ "New", "Solved", "Planned", "InProgress" ] }, "title": { "description": "Title of the opportunity", "example": "Improve Customer Onboarding Experience", "type": "string" }, "description": { "description": "Description of the opportunity", "example": "Streamline the initial user setup process to reduce drop-offs", "type": "string" }, "solutionsGeneratingState": { "description": "Current state of solution generation", "example": "initial", "type": "string", "enum": [ "generating", "generated", "initial", "error" ] }, "createdBy": { "description": "How the opportunity was created", "example": "user", "type": "string", "enum": [ "user", "generated" ] }, "hideContent": { "description": "Whether the opportunity content should be hidden", "example": false, "type": "boolean" }, "ownerId": { "description": "ID of the opportunity owner", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4", "type": "string" }, "createdAt": { "description": "Creation timestamp", "example": "2023-01-01T00:00:00.000Z", "type": "string" }, "updatedAt": { "description": "Last update timestamp", "example": "2023-01-01T00:00:00.000Z", "type": "string" } }, "required": [ "id", "read", "status", "title", "description", "solutionsGeneratingState", "createdBy", "hideContent", "createdAt", "updatedAt" ], "additionalProperties": false }, "Solution": { "description": "Solution data for an opportunity", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "systemPrompt": { "description": "System prompt used to generate the requirement", "example": "Hello", "type": "string" }, "aiProcessingState": { "description": "Current state of AI processing", "example": "FINISHED", "type": "string", "enum": [ "INITIAL", "PROCESSING", "FINISHED", "ERROR" ] }, "refinementLog": { "description": "Log of refinements made to the requirement", "example": [], "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique identifier for the log entry", "example": "96dafa28-1e01-4ba4-a92b-babb8b792823", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "role": { "description": "Role of the entity making the log entry", "example": "assistant", "type": "string", "enum": [ "user", "assistant" ] }, "content": { "description": "Content of the log entry", "example": "Initial requirement", "type": "string" } }, "required": [ "id", "role", "content" ], "additionalProperties": false } }, "title": { "description": "Title of the solution", "example": "Implement Single Sign-On", "type": "string" }, "description": { "description": "Description of the solution", "example": "Integrate with OAuth providers to simplify user login experience", "type": "string" }, "status": { "description": "Solution status", "example": "Backlog", "type": "string", "enum": [ "Backlog", "New", "Planned", "InDevelopment", "Complete", "Cancelled", "Live" ] }, "pros": { "description": "List of pros/advantages for this solution", "example": [ "Improved security", "Simplified login flow", "Reduced password reset requests" ], "type": "array", "items": { "type": "string" } }, "cons": { "description": "List of cons/disadvantages for this solution", "example": [ "Requires integration with external providers", "May add complexity to registration" ], "type": "array", "items": { "type": "string" } }, "hideContent": { "description": "Whether the solution content should be hidden", "example": false, "type": "boolean" }, "createdBy": { "description": "How the solution was created", "example": "generated", "type": "string", "enum": [ "user", "generated" ] }, "ownerId": { "description": "ID of the solution owner", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4", "type": "string" }, "createdAt": { "description": "Creation timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "updatedAt": { "description": "Last update timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "priority": { "description": "User indicated priority for the solution (fractional-indexing string)", "example": "a0", "type": "string" }, "prd": { "description": "Product Requirements Document content for the solution", "example": "Objective: Help users easily create...", "type": "string" }, "horizon": { "description": "Time horizon for the solution", "example": "now", "type": "string", "enum": [ "now", "next", "later" ] } }, "required": [ "id", "aiProcessingState", "refinementLog", "title", "description", "status", "pros", "cons", "hideContent", "createdBy", "createdAt", "updatedAt", "priority", "prd" ], "additionalProperties": false }, "Insight": { "description": "Insight data from a user", "type": "object", "properties": { "id": { "description": "Unique identifier for the insight", "example": "d231fe70-9585-4657-9c4e-6b431bbc1b6a", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "type": { "description": "Type of insight", "example": "Feedback", "type": "string", "enum": [ "Feedback", "Bug", "FeatureRequest" ] }, "title": { "description": "Title of the insight", "example": "Dashboard UX Improvements", "type": "string" }, "description": { "description": "Description of the insight", "example": "The dashboard could use better data visualization", "type": "string" }, "seen": { "description": "Whether the insight has been seen", "example": false, "type": "boolean" }, "hideContent": { "description": "Whether the insight content should be hidden", "example": false, "type": "boolean" }, "ownerId": { "description": "ID of the insight owner", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4", "type": "string" }, "strengthScore": { "description": "Wilson score + corroboration score (0-1)", "example": 0.75, "type": "number", "minimum": 0, "maximum": 1 }, "momentumScore": { "description": "Recency and burst detection score", "example": 0.5, "type": "number", "minimum": 0 }, "combinedScore": { "description": "Weighted composite of strength and momentum scores", "example": 0.65, "type": "number", "minimum": 0 }, "lastScoreCalculatedAt": { "description": "ISO timestamp of last score calculation", "example": "2025-03-26T22:35:46Z", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "topicEmbeddings": { "description": "BERT embeddings for topic modeling", "example": [ 0.1, -0.2, 0.3 ], "type": "array", "items": { "type": "number" } }, "createdAt": { "description": "Creation timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "updatedAt": { "description": "Last update timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" } }, "required": [ "id", "type", "title", "description", "seen", "hideContent", "createdAt", "updatedAt" ], "additionalProperties": false }, "Metric": { "description": "Metric data representing a measurable KPI result", "type": "object", "properties": { "id": { "description": "Unique identifier for the metric", "example": "7b9e5d2c-f314-48a9-be56-9843a2f6c019", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "description": "Display name for the metric", "example": "Daily Active Users", "type": "string" }, "description": { "description": "Detailed description of the metric", "example": "Number of unique users who performed any action in the last 24 hours", "type": "string" }, "unit": { "description": "Unit of measurement for the metric", "example": "users", "type": "string" }, "type": { "description": "Category/type of the metric", "default": "custom", "type": "string", "enum": [ "engagement", "conversion", "revenue", "nps", "csat", "ces", "ratio", "custom" ] }, "targetOperator": { "description": "Comparison operator for the target", "type": "string", "enum": [ "greater_than", "less_than", "equal_to" ] }, "targetValue": { "description": "Target value to achieve", "example": 100, "type": "number" }, "targetDirection": { "description": "Direction of improvement (up = higher is better, down = lower is better)", "default": "up", "type": "string", "enum": [ "up", "down" ] }, "currentValue": { "description": "Current value of the metric", "example": 150, "type": "number" }, "previousValue": { "description": "Previous value of the metric for comparison", "example": 140, "type": "number" }, "periodType": { "description": "Type of period for metric comparison", "example": "calendar", "type": "string", "enum": [ "rolling", "calendar" ] }, "periodValue": { "description": "Specific period value for metric comparison", "example": "month", "type": "string", "enum": [ "day", "week", "month", "quarter", "year", "7-day", "30-day", "90-day" ] }, "ownerId": { "description": "UserId of the Owner/responsible person for this metric", "example": "user_123456789", "type": "string" }, "timeseries": { "description": "Historical values for trend analysis", "type": "array", "items": { "$ref": "#/components/schemas/MetricTimeseriesPointOutput" } }, "createdAt": { "description": "Timestamp of when the metric was created", "example": "2023-01-01T00:00:00.000Z", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "description": "Timestamp of when the metric was last updated", "example": "2023-01-01T00:00:00.000Z", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "relatedOutcomes": { "description": "Related outcomes that use this metric", "type": "array", "items": {} } }, "required": [ "id", "title", "ownerId", "createdAt", "updatedAt" ], "additionalProperties": false }, "Outcome": { "description": "Outcome data representing a business objective", "type": "object", "properties": { "id": { "description": "Unique identifier for the outcome", "example": "7b9e5d2c-f314-48a9-be56-9843a2f6c019", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "description": "Title of the outcome", "example": "Increase User Engagement", "type": "string" }, "description": { "description": "Detailed description of the outcome", "example": "We aim to increase daily active users by 25% in Q3", "type": "string" }, "priority": { "description": "Priority level of the outcome", "example": 1, "type": "number" }, "trend": { "description": "Trend indicator for the outcome", "example": 0, "type": "number" }, "analyticEvents": { "description": "List of analytic events associated with the outcome", "example": [ "event1", "event2" ], "type": "array", "items": { "type": "string" } }, "hideContent": { "description": "Whether the outcome is hidden", "example": false, "type": "boolean" }, "ownerId": { "description": "ID of the owner of the outcome", "example": "7b9e5d2c-f314-48a9-be56-9843a2f6c019", "type": "string" }, "createdAt": { "description": "Timestamp of when the outcome was created", "example": "2023-01-01T00:00:00.000Z", "type": "string" }, "updatedAt": { "description": "Timestamp of when the outcome was last updated", "example": "2023-01-01T00:00:00.000Z", "type": "string" } }, "required": [ "id", "title", "description", "priority", "hideContent", "createdAt", "updatedAt" ], "additionalProperties": false }, "OnboardingResponse": { "description": "Response schema for onboarding", "type": "object", "properties": { "data": { "type": "object", "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" }, "outcomes": { "description": "Array of outcomes", "type": "array", "items": { "$ref": "#/components/schemas/Outcome" } }, "organisation": { "type": "object", "properties": { "id": { "description": "Unique identifier for the organization", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "description": "Name of the organization", "example": "Acme Corporation", "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "workspace", "outcomes", "organisation" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "Workspace": { "description": "Workspace data", "type": "object", "properties": { "id": { "description": "ID of the workspace", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "description": "Name of the workspace", "example": "Product Development", "type": "string" }, "homepageUrl": { "description": "URL to the workspace's homepage", "example": "https://product.example.com", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "logoUrl": { "description": "URL to the workspace's logo", "example": "https://product.example.com/logo.png", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "missionStatement": { "description": "Mission statement for the workspace", "example": "Develop innovative products that solve real customer problems", "type": "string" }, "description": { "description": "Detailed description of the workspace", "example": "This workspace focuses on our core product development initiatives, including roadmap planning, feature development, and product improvements.", "type": "string" }, "createdAt": { "description": "Creation timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "updatedAt": { "description": "Last update timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "status": { "description": "Status of the workspace", "example": "Initializing", "type": "string", "enum": [ "Initializing", "OnboardingDeepResearch", "OnboardingConsiderWorkspace", "OnboardingConsiderOpportunities", "OnboardingConsiderOpportunitiesToOutcomes", "OnboardingConsiderSolutionGeneration", "OnboardingConsiderSolutionsToBuild", "OnboardingSelectSolutionsToBuild", "OnboardingMapSolutionsToRoadmap", "Active", "Inactive" ] } }, "required": [ "id", "name", "missionStatement", "createdAt", "updatedAt", "status" ], "additionalProperties": false }, "FeedbackWithRelationships": { "description": "Raw feedback with generated insights", "type": "object", "properties": { "id": { "description": "Unique identifier for the feedback", "example": "f5d8df32-60b4-417a-8b83-8d4dcb4e88e1", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "content": { "description": "Original raw feedback content", "example": "I found the dashboard charts difficult to understand at first glance. The colors are confusing and the data is hard to interpret.", "type": "string" }, "source": { "description": "Source of the feedback", "example": "Customer Interview", "type": "string" }, "submittedBy": { "description": "ID of the user who submitted this feedback", "example": "user_123", "type": "string" }, "processed": { "description": "Whether this feedback has been processed into insights", "example": false, "type": "boolean" }, "sentimentScore": { "description": "Sentiment score from -1 (negative) to 1 (positive)", "example": 0.75, "type": "number", "minimum": -1, "maximum": 1 }, "sentimentCategory": { "description": "Sentiment classification category", "example": "Positive", "type": "string", "enum": [ "Positive", "Neutral", "Negative" ] }, "sentimentConfidence": { "description": "Confidence in sentiment analysis (0-1)", "example": 0.95, "type": "number", "minimum": 0, "maximum": 1 }, "createdAt": { "description": "Creation timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "createdAtEpoch": { "description": "Unix epoch timestamp for efficient Neo4j queries", "example": 1679867746, "type": "number" }, "updatedAt": { "description": "Last update timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "insights": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Insight" } } }, "required": [ "id", "content", "source", "processed", "createdAt", "updatedAt", "insights" ], "additionalProperties": false }, "FeedbackArrayResponse": { "description": "Response containing an array of feedback items", "type": "object", "properties": { "data": { "description": "Array of feedback items", "type": "array", "items": { "$ref": "#/components/schemas/FeedbackWithRelationships" } } }, "required": [ "data" ], "additionalProperties": false }, "InsightWithRelationships": { "description": "Insight with relationships (legacy - use InsightWithRelationships)", "type": "object", "properties": { "id": { "description": "Unique identifier for the insight", "example": "d231fe70-9585-4657-9c4e-6b431bbc1b6a", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "type": { "description": "Type of insight", "example": "Feedback", "type": "string", "enum": [ "Feedback", "Bug", "FeatureRequest" ] }, "title": { "description": "Title of the insight", "example": "Dashboard UX Improvements", "type": "string" }, "description": { "description": "Description of the insight", "example": "The dashboard could use better data visualization", "type": "string" }, "seen": { "description": "Whether the insight has been seen", "example": false, "type": "boolean" }, "hideContent": { "description": "Whether the insight content should be hidden", "example": false, "type": "boolean" }, "ownerId": { "description": "ID of the insight owner", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4", "type": "string" }, "strengthScore": { "description": "Wilson score + corroboration score (0-1)", "example": 0.75, "type": "number", "minimum": 0, "maximum": 1 }, "momentumScore": { "description": "Recency and burst detection score", "example": 0.5, "type": "number", "minimum": 0 }, "combinedScore": { "description": "Weighted composite of strength and momentum scores", "example": 0.65, "type": "number", "minimum": 0 }, "lastScoreCalculatedAt": { "description": "ISO timestamp of last score calculation", "example": "2025-03-26T22:35:46Z", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "topicEmbeddings": { "description": "BERT embeddings for topic modeling", "example": [ 0.1, -0.2, 0.3 ], "type": "array", "items": { "type": "number" } }, "createdAt": { "description": "Creation timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "updatedAt": { "description": "Last update timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "opportunities": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Opportunity" } }, "solutions": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Solution" } }, "outcomes": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Outcome" } }, "feedback": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Feedback" } }, "strength": { "description": "The number of connections this insight has to other entities", "example": 5, "default": 0, "type": "number" } }, "required": [ "id", "type", "title", "description", "seen", "hideContent", "createdAt", "updatedAt", "opportunities", "solutions", "outcomes", "feedback", "strength" ], "additionalProperties": false }, "Feedback": { "description": "Raw feedback data from a user", "type": "object", "properties": { "id": { "description": "Unique identifier for the feedback", "example": "f5d8df32-60b4-417a-8b83-8d4dcb4e88e1", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "content": { "description": "Original raw feedback content", "example": "I found the dashboard charts difficult to understand at first glance. The colors are confusing and the data is hard to interpret.", "type": "string" }, "source": { "description": "Source of the feedback", "example": "Customer Interview", "type": "string" }, "submittedBy": { "description": "ID of the user who submitted this feedback", "example": "user_123", "type": "string" }, "processed": { "description": "Whether this feedback has been processed into insights", "example": false, "type": "boolean" }, "sentimentScore": { "description": "Sentiment score from -1 (negative) to 1 (positive)", "example": 0.75, "type": "number", "minimum": -1, "maximum": 1 }, "sentimentCategory": { "description": "Sentiment classification category", "example": "Positive", "type": "string", "enum": [ "Positive", "Neutral", "Negative" ] }, "sentimentConfidence": { "description": "Confidence in sentiment analysis (0-1)", "example": 0.95, "type": "number", "minimum": 0, "maximum": 1 }, "createdAt": { "description": "Creation timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "createdAtEpoch": { "description": "Unix epoch timestamp for efficient Neo4j queries", "example": 1679867746, "type": "number" }, "updatedAt": { "description": "Last update timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" } }, "required": [ "id", "content", "source", "processed", "createdAt", "updatedAt" ], "additionalProperties": false }, "InsightArrayResponse": { "description": "Response containing an array of insight items", "type": "object", "properties": { "data": { "description": "Array of insight items", "type": "array", "items": { "$ref": "#/components/schemas/InsightWithRelationships" } } }, "required": [ "data" ], "additionalProperties": false }, "MockInsightsResponse": { "description": "Array of mock insights", "type": "array", "items": { "type": "object", "properties": { "description": { "description": "Description of the insight", "example": "Pet Stay Properties exceeded our expectations with their exceptional service and spotless accommodations.", "type": "string" }, "feedback": { "description": "Original feedback text that generated this insight", "example": "We recently booked a stay for our furry friend at Pet Stay Properties and were blown away by the level of service and cleanliness. The property was immaculate, and the staff went above and beyond to ensure our pet's comfort. We will definitely be using them again!", "type": "string" }, "title": { "description": "Title of the insight", "example": "Excellent Service and Cleanliness", "type": "string" }, "type": { "description": "Type of the original feedback", "example": "Feedback", "type": "string", "enum": [ "Feedback", "Bug", "FeatureRequest" ] } }, "required": [ "description", "feedback", "title", "type" ], "additionalProperties": false } }, "Integration": { "description": "Integration record", "oneOf": [ { "$ref": "#/components/schemas/NotionIntegration" }, { "$ref": "#/components/schemas/TypeformIntegration" } ], "type": "object", "discriminator": { "propertyName": "integrationId", "mapping": { "NOTION": "#/components/schemas/NotionIntegration", "TYPEFORM": "#/components/schemas/TypeformIntegration" } } }, "NotionIntegration": { "description": "Notion integration record", "type": "object", "properties": { "id": { "type": "number" }, "integrationId": { "type": "string", "const": "NOTION" }, "workspaceId": { "type": "string" }, "organisationId": { "type": "string" }, "config": { "$ref": "#/components/schemas/NotionResponseConfig" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "integrationId", "workspaceId", "organisationId", "config", "createdAt", "updatedAt" ], "additionalProperties": false }, "NotionResponseConfig": { "description": "Notion integration configuration in API response (sanitized)", "type": "object", "properties": { "active": { "description": "Whether the Notion integration is active", "example": false, "type": "boolean" }, "created_by": { "description": "User ID who created this integration", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4", "type": "string" }, "last_synced_at": { "description": "Last time data was synced from Notion", "example": "2025-03-26T22:35:46Z", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "active", "created_by" ], "additionalProperties": false }, "TypeformIntegration": { "description": "Typeform integration record", "type": "object", "properties": { "id": { "type": "number" }, "integrationId": { "type": "string", "const": "TYPEFORM" }, "workspaceId": { "type": "string" }, "organisationId": { "type": "string" }, "config": { "$ref": "#/components/schemas/TypeformResponseConfig" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "integrationId", "workspaceId", "organisationId", "config", "createdAt", "updatedAt" ], "additionalProperties": false }, "TypeformResponseConfig": { "description": "Typeform integration configuration in API response (sanitized)", "type": "object", "properties": { "active": { "description": "Whether the Typeform integration is active", "example": true, "type": "boolean" }, "created_by": { "description": "User ID who created this integration", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4", "type": "string" } }, "required": [ "active", "created_by" ], "additionalProperties": false }, "OpportunityResponse": { "description": "Response containing a single opportunity", "type": "object", "properties": { "data": { "description": "Opportunity data", "type": "object", "properties": { "id": { "description": "Unique identifier for the opportunity", "example": "f5d8df32-60b4-417a-8b83-8d4dcb4e88e1", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "read": { "description": "Whether the opportunity has been read", "example": false, "type": "boolean" }, "status": { "description": "Current status of the opportunity", "example": "New", "type": "string", "enum": [ "New", "Solved", "Planned", "InProgress" ] }, "title": { "description": "Title of the opportunity", "example": "Improve Customer Onboarding Experience", "type": "string" }, "description": { "description": "Description of the opportunity", "example": "Streamline the initial user setup process to reduce drop-offs", "type": "string" }, "solutionsGeneratingState": { "description": "Current state of solution generation", "example": "initial", "type": "string", "enum": [ "generating", "generated", "initial", "error" ] }, "createdBy": { "description": "How the opportunity was created", "example": "user", "type": "string", "enum": [ "user", "generated" ] }, "hideContent": { "description": "Whether the opportunity content should be hidden", "example": false, "type": "boolean" }, "ownerId": { "description": "ID of the opportunity owner", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4", "type": "string" }, "createdAt": { "description": "Creation timestamp", "example": "2023-01-01T00:00:00.000Z", "type": "string" }, "updatedAt": { "description": "Last update timestamp", "example": "2023-01-01T00:00:00.000Z", "type": "string" }, "hasUnseenInsights": { "description": "Whether the opportunity has unseen insights", "example": false, "type": "boolean" }, "solutions": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Solution" } }, "insights": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Insight" } }, "outcomes": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Outcome" } }, "topics": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Topic" } } }, "required": [ "id", "read", "status", "title", "description", "solutionsGeneratingState", "createdBy", "hideContent", "createdAt", "updatedAt", "hasUnseenInsights", "solutions", "insights", "outcomes", "topics" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "Topic": { "description": "Topic data for organizing insight", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "description": "Title of the topic", "example": "User Interface Improvements", "type": "string" }, "description": { "description": "Description of the topic", "example": "General insight related to UI/UX improvements", "type": "string" }, "createdAt": { "description": "Creation timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "updatedAt": { "description": "Last update timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" } }, "required": [ "id", "title", "description", "createdAt", "updatedAt" ], "additionalProperties": false }, "OpportunityArrayResponse": { "description": "Response containing an array of opportunities", "type": "object", "properties": { "data": { "description": "Array of opportunities", "type": "array", "items": { "$ref": "#/components/schemas/OpportunityWithRelationships" } } }, "required": [ "data" ], "additionalProperties": false }, "OpportunityWithRelationships": { "description": "Opportunity with relationships", "type": "object", "properties": { "id": { "description": "Unique identifier for the opportunity", "example": "f5d8df32-60b4-417a-8b83-8d4dcb4e88e1", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "read": { "description": "Whether the opportunity has been read", "example": false, "type": "boolean" }, "status": { "description": "Current status of the opportunity", "example": "New", "type": "string", "enum": [ "New", "Solved", "Planned", "InProgress" ] }, "title": { "description": "Title of the opportunity", "example": "Improve Customer Onboarding Experience", "type": "string" }, "description": { "description": "Description of the opportunity", "example": "Streamline the initial user setup process to reduce drop-offs", "type": "string" }, "solutionsGeneratingState": { "description": "Current state of solution generation", "example": "initial", "type": "string", "enum": [ "generating", "generated", "initial", "error" ] }, "createdBy": { "description": "How the opportunity was created", "example": "user", "type": "string", "enum": [ "user", "generated" ] }, "hideContent": { "description": "Whether the opportunity content should be hidden", "example": false, "type": "boolean" }, "ownerId": { "description": "ID of the opportunity owner", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4", "type": "string" }, "createdAt": { "description": "Creation timestamp", "example": "2023-01-01T00:00:00.000Z", "type": "string" }, "updatedAt": { "description": "Last update timestamp", "example": "2023-01-01T00:00:00.000Z", "type": "string" }, "hasUnseenInsights": { "description": "Whether the opportunity has unseen insights", "example": false, "default": false, "type": "boolean" }, "solutions": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Solution" } }, "insights": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Insight" } }, "outcomes": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Outcome" } }, "topics": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Topic" } } }, "required": [ "id", "read", "status", "title", "description", "solutionsGeneratingState", "createdBy", "hideContent", "createdAt", "updatedAt", "hasUnseenInsights", "solutions", "insights", "outcomes", "topics" ], "additionalProperties": false }, "SolutionWithRelationships": { "description": "Solution with relationships", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "systemPrompt": { "description": "System prompt used to generate the requirement", "example": "Hello", "type": "string" }, "aiProcessingState": { "description": "Current state of AI processing", "example": "FINISHED", "type": "string", "enum": [ "INITIAL", "PROCESSING", "FINISHED", "ERROR" ] }, "refinementLog": { "description": "Log of refinements made to the requirement", "example": [], "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique identifier for the log entry", "example": "96dafa28-1e01-4ba4-a92b-babb8b792823", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "role": { "description": "Role of the entity making the log entry", "example": "assistant", "type": "string", "enum": [ "user", "assistant" ] }, "content": { "description": "Content of the log entry", "example": "Initial requirement", "type": "string" } }, "required": [ "id", "role", "content" ], "additionalProperties": false } }, "title": { "description": "Title of the solution", "example": "Implement Single Sign-On", "type": "string" }, "description": { "description": "Description of the solution", "example": "Integrate with OAuth providers to simplify user login experience", "type": "string" }, "status": { "description": "Solution status", "example": "Backlog", "type": "string", "enum": [ "Backlog", "New", "Planned", "InDevelopment", "Complete", "Cancelled", "Live" ] }, "pros": { "description": "List of pros/advantages for this solution", "example": [ "Improved security", "Simplified login flow", "Reduced password reset requests" ], "type": "array", "items": { "type": "string" } }, "cons": { "description": "List of cons/disadvantages for this solution", "example": [ "Requires integration with external providers", "May add complexity to registration" ], "type": "array", "items": { "type": "string" } }, "hideContent": { "description": "Whether the solution content should be hidden", "example": false, "type": "boolean" }, "createdBy": { "description": "How the solution was created", "example": "generated", "type": "string", "enum": [ "user", "generated" ] }, "ownerId": { "description": "ID of the solution owner", "example": "d4e71c2b-a498-42af-b7f5-69de06a0d7c4", "type": "string" }, "createdAt": { "description": "Creation timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "updatedAt": { "description": "Last update timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "priority": { "description": "User indicated priority for the solution (fractional-indexing string)", "example": "a0", "type": "string" }, "prd": { "description": "Product Requirements Document content for the solution", "example": "Objective: Help users easily create...", "type": "string" }, "horizon": { "description": "Time horizon for the solution", "example": "now", "type": "string", "enum": [ "now", "next", "later" ] }, "opportunities": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Opportunity" } }, "insights": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Insight" } }, "outcomes": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Outcome" } } }, "required": [ "id", "aiProcessingState", "refinementLog", "title", "description", "status", "pros", "cons", "hideContent", "createdBy", "createdAt", "updatedAt", "priority", "prd", "opportunities", "insights", "outcomes" ], "additionalProperties": false }, "TopicWithRelationships": { "description": "Topic data", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "description": "Title of the topic", "example": "User Interface Improvements", "type": "string" }, "description": { "description": "Description of the topic", "example": "General insight related to UI/UX improvements", "type": "string" }, "createdAt": { "description": "Creation timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "updatedAt": { "description": "Last update timestamp", "example": "2025-03-26T22:35:46Z", "type": "string" }, "opportunities": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Opportunity" } }, "insights": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/Insight" } }, "opportunityCount": { "description": "Number of opportunities associated with the topic", "example": 1, "type": "number" } }, "required": [ "id", "title", "description", "createdAt", "updatedAt", "opportunities", "insights", "opportunityCount" ], "additionalProperties": false }, "Organisation": { "description": "Number of unprocessed insight items", "example": 123, "type": "number" }, "WhoAmIResponse": { "description": "User organization and workspace information", "type": "object", "properties": { "data": { "type": "object", "properties": { "organisation": { "type": "object", "properties": { "id": { "description": "Organization ID", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "description": "Organization name", "example": "Acme Corporation", "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "workspace": { "type": "object", "properties": { "id": { "description": "Workspace ID", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "description": "Workspace name", "example": "Product Development", "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "organisation", "workspace" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "InsightResponse": { "description": "Response data for processed insight", "type": "object", "properties": { "insight": { "description": "The insight content", "example": "I had trouble with the checkout process on your website", "type": "string" }, "source": { "description": "The source of the insight", "example": "SLACK", "$ref": "#/components/schemas/InsightSourceEnum" }, "workspaceId": { "description": "ID of the workspace", "example": "c0e195d9-b918-4a3a-bd8b-f730361d044f", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "organisationId": { "description": "ID of the organization", "example": "a5f3c6e1-9d20-4f7b-8e31-d09a2b63c184", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "insight", "source", "workspaceId", "organisationId" ], "additionalProperties": false }, "InsightSourceEnum": { "description": "The source of the insight", "example": "TYPEFORM", "type": "string", "enum": [ "TYPEFORM", "SLACK", "UNKNOWN", "MANUAL" ] }, "CreateFeedbackDocumentResponse": { "description": "Uploaded document information", "type": "object", "properties": { "data": { "type": "object", "properties": { "uploadUrl": { "description": "A secure URL to upload the document to", "example": "https://example.com/documents/doc_123?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...", "type": "string" } }, "required": [ "uploadUrl" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "SingleKnowledgeResponse": { "description": "Response containing a single knowledge", "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SingleKnowledgeResponseData" } }, "required": [ "data" ], "additionalProperties": false }, "SingleKnowledgeResponseData": { "description": "Response containing a single knowledge", "type": "object", "properties": { "id": { "description": "Knowledge ID", "example": "7b9e5d2c-f314-48a9-be56-9843a2f6c019", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "state": { "description": "Knowledge state", "example": "initial", "type": "string", "enum": [ "initial", "processing", "completed", "error" ] }, "title": { "description": "Knowledge title", "example": "Best practices for AI in healthcare", "type": "string" }, "description": { "description": "Knowledge description - a short summary of the knowledge", "example": "A collection of best practices for AI in healthcare", "type": "string" }, "createdAt": { "description": "Knowledge creation timestamp", "example": "2023-01-01T00:00:00.000Z", "type": "string" }, "updatedAt": { "description": "Knowledge update timestamp", "example": "2023-01-01T00:00:00.000Z", "type": "string" }, "source": { "description": "Type of knowledge", "example": "text", "type": "string", "enum": [ "text", "url", "pdf" ] }, "providedBy": { "description": "Integration node type that provides this knowledge (calculated field from PROVIDES relationship)", "example": "NotionPage", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pdfFileUrl": { "description": "URL of the PDF file of the knowledge (mutually exclusive with url)", "example": "https://example.com/document.pdf", "type": "string" }, "txtFileUrl": { "description": "URL of the TXT file of the knowledge (mutually exclusive with url)", "example": "/knowledge/7b9e5d2c-f314-48a9-be56-9843a2f6c019", "type": "string" }, "url": { "description": "URL of the knowledge source (mutually exclusive with filePath)", "example": "https://example.com/document.pdf", "type": "string", "format": "uri" }, "content": { "description": "Knowledge content - the full content of the knowledge, this will only be available post processing", "example": "A collection of best practices for AI in healthcare", "type": "string" } }, "required": [ "id", "state", "title", "description", "createdAt", "updatedAt", "source", "providedBy" ], "additionalProperties": false }, "SingleKnowledgeResponseWithUploadPdf": { "description": "Response containing a single knowledge", "type": "object", "properties": { "id": { "description": "Knowledge ID", "example": "7b9e5d2c-f314-48a9-be56-9843a2f6c019", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "state": { "description": "Knowledge state", "example": "initial", "type": "string", "enum": [ "initial", "processing", "completed", "error" ] }, "title": { "description": "Knowledge title", "example": "Best practices for AI in healthcare", "type": "string" }, "description": { "description": "Knowledge description - a short summary of the knowledge", "example": "A collection of best practices for AI in healthcare", "type": "string" }, "createdAt": { "description": "Knowledge creation timestamp", "example": "2023-01-01T00:00:00.000Z", "type": "string" }, "updatedAt": { "description": "Knowledge update timestamp", "example": "2023-01-01T00:00:00.000Z", "type": "string" }, "source": { "description": "Type of knowledge", "example": "text", "type": "string", "enum": [ "text", "url", "pdf" ] }, "providedBy": { "description": "Integration node type that provides this knowledge (calculated field from PROVIDES relationship)", "example": "NotionPage", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pdfFileUrl": { "description": "URL of the PDF file of the knowledge (mutually exclusive with url)", "example": "https://example.com/document.pdf", "type": "string" }, "txtFileUrl": { "description": "URL of the TXT file of the knowledge (mutually exclusive with url)", "example": "/knowledge/7b9e5d2c-f314-48a9-be56-9843a2f6c019", "type": "string" }, "url": { "description": "URL of the knowledge source (mutually exclusive with filePath)", "example": "https://example.com/document.pdf", "type": "string", "format": "uri" }, "uploadUrl": { "description": "The single use secure S3 upload url.", "example": "https://s3.amazonaws.com/basilisk-ai-dev/example.pdf", "type": "string" } }, "required": [ "id", "state", "title", "description", "createdAt", "updatedAt", "source", "providedBy", "uploadUrl" ], "additionalProperties": false }, "KnowledgeArrayResponse": { "description": "Response containing an array of knowledge", "type": "object", "properties": { "data": { "description": "Array of knowledge", "type": "array", "items": { "$ref": "#/components/schemas/Knowledge" } } }, "required": [ "data" ], "additionalProperties": false }, "Knowledge": { "description": "Knowledge entity schema", "type": "object", "properties": { "id": { "description": "Knowledge ID", "example": "7b9e5d2c-f314-48a9-be56-9843a2f6c019", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "state": { "description": "Knowledge state", "example": "initial", "type": "string", "enum": [ "initial", "processing", "completed", "error" ] }, "title": { "description": "Knowledge title", "example": "Best practices for AI in healthcare", "type": "string" }, "description": { "description": "Knowledge description - a short summary of the knowledge", "example": "A collection of best practices for AI in healthcare", "type": "string" }, "createdAt": { "description": "Knowledge creation timestamp", "example": "2023-01-01T00:00:00.000Z", "type": "string" }, "updatedAt": { "description": "Knowledge update timestamp", "example": "2023-01-01T00:00:00.000Z", "type": "string" }, "source": { "description": "Type of knowledge", "example": "text", "type": "string", "enum": [ "text", "url", "pdf" ] }, "providedBy": { "description": "Integration node type that provides this knowledge (calculated field from PROVIDES relationship)", "example": "NotionPage", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pdfFileUrl": { "description": "URL of the PDF file of the knowledge (mutually exclusive with url)", "example": "https://example.com/document.pdf", "type": "string" }, "txtFileUrl": { "description": "URL of the TXT file of the knowledge (mutually exclusive with url)", "example": "/knowledge/7b9e5d2c-f314-48a9-be56-9843a2f6c019", "type": "string" }, "url": { "description": "URL of the knowledge source (mutually exclusive with filePath)", "example": "https://example.com/document.pdf", "type": "string", "format": "uri" } }, "required": [ "id", "state", "title", "description", "createdAt", "updatedAt", "source", "providedBy" ], "additionalProperties": false }, "UpdateStrategyDocumentPayload": { "description": "Request schema for updating a strategy document", "type": "object", "properties": { "data": { "type": "object", "properties": { "report": { "description": "Strategy document report", "example": "# Strategy Document\n## Mission\n...", "type": "string" } }, "required": [ "report" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "SimilaritySearchResponse": { "description": "Similarity search response data", "type": "object", "properties": { "opportunities": { "description": "Array of matched opportunities", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "score": { "type": "number" }, "metadata": { "type": "object", "properties": { "nodeId": { "type": "string" }, "content": { "type": "string" } }, "required": [ "nodeId" ], "additionalProperties": false } }, "required": [ "id" ], "additionalProperties": false } }, "knowledge": { "description": "Array of matched knowledge items", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "score": { "type": "number" }, "metadata": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false } }, "required": [ "id" ], "additionalProperties": false } }, "insights": { "description": "Array of matched insights items", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "score": { "type": "number" }, "metadata": { "type": "object", "properties": { "nodeId": { "type": "string" }, "insightId": { "type": "string" }, "content": { "type": "string" } }, "required": [ "nodeId" ], "additionalProperties": false } }, "required": [ "id" ], "additionalProperties": false } }, "solutions": { "description": "Array of matched solutions items", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "score": { "type": "number" }, "metadata": { "type": "object", "properties": { "nodeId": { "type": "string" }, "status": { "description": "Solution status", "example": "Backlog", "type": "string", "enum": [ "Backlog", "New", "Planned", "InDevelopment", "Complete", "Cancelled", "Live" ] }, "content": { "type": "string" } }, "required": [ "nodeId", "status" ], "additionalProperties": false } }, "required": [ "id" ], "additionalProperties": false } }, "totalResults": { "description": "Total number of results", "type": "number" } }, "additionalProperties": false }, "MetricTimeseriesPointOutput": { "description": "A single data point in a metric's time series", "type": "object", "properties": { "date": { "description": "ISO datetime string for the data point", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "value": { "description": "Metric value at this point in time", "example": 85, "type": "number" } }, "required": [ "date", "value" ], "additionalProperties": false } }, "parameters": { "OutcomeRelationshipsParam": { "in": "query", "name": "relationships", "schema": { "type": "string" }, "required": false, "description": "Comma-separated list of relationships to include in the response", "example": "opportunities,solutions,insights,metrics" }, "FeedbackRelationshipsParam": { "in": "query", "name": "relationships", "schema": { "type": "string" }, "required": false, "description": "Comma-separated list of relationships to include in the response", "example": "insights" }, "InsightRelationshipsParam": { "in": "query", "name": "relationships", "schema": { "type": "string" }, "required": false, "description": "Comma-separated list of relationships to include in the response", "example": "opportunities,solutions,outcomes" }, "OpportunityRelationshipsParam": { "in": "query", "name": "relationships", "schema": { "type": "string" }, "required": false, "description": "Comma-separated list of relationships to include in the response", "example": "solutions,outcomes,insights" }, "SolutionRelationshipsParam": { "in": "query", "name": "relationships", "schema": { "type": "string" }, "required": false, "description": "Comma-separated list of relationships to include in the response", "example": "opportunities,outcomes,insighs" } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT authentication for organization-scoped endpoints." }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "API key authentication for public API endpoints. This key is scoped by workspace so a unique key is required per workspace within an organisation." } } } }