{ "openapi": "3.1.0", "info": { "title": "VistaCX Customer API", "version": "0.8.0-draft", "description": "VistaCX beta API reference. Hosted API access is not yet enabled. Examples are illustrative." }, "servers": [ { "url": "https://api.vistacx-demo.cxfabric.io/api/v1", "description": "Planned beta API endpoint — not yet enabled" } ], "security": [ { "apiToken": [] } ], "paths": { "/projects": { "get": { "operationId": "listProjects", "summary": "List projects", "x-required-scopes": [ "projects:read" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Use nextCursor from the preceding page unchanged. If it expires or the collection changes, restart from the first page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Maximum number of items to return on this page; follow the allowed range in the schema.", "example": 20 } ], "responses": { "200": { "description": "Illustrative success response. IDs and values below are examples; actual responses reflect your authorized records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectPage" }, "example": { "items": [ { "id": "project_example", "version": 1, "name": "Customer service testing", "description": "Example workspace project" } ], "nextCursor": null, "requestId": "request_example" } } }, "headers": { "ETag": { "schema": { "type": "string", "maxLength": 4000 }, "description": "Opaque resource version; required as If-Match for updates when resource is versioned." } } }, "429": { "description": "Request limit exceeded. Wait for the interval indicated by Retry-After before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error response. 400: invalid request; 401: missing, expired or invalid token; 403: permission denied; 404: record not available to this token; 409: conflict; 412: stale version; 422: invalid fields; 429: rate limit; 503: temporarily unavailable. Handle the returned code and retain requestId for support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "not_found", "status": 404, "code": "not_found", "detail": "Resource not found.", "requestId": "request_example" } } } } }, "description": "Projects organize related Systems and test work within your workspace.\n\nList the records you are permitted to read. Use this to locate IDs for subsequent requests.\n\nRead-only. No records or evidence are changed.\n\nAccess is limited to the workspace and Projects authorized by your API token. IDs do not grant access to another workspace.", "x-related-operations": [ "createSystem", "listSystems" ], "x-availability": "preview" }, "post": { "operationId": "createProject", "summary": "Create project", "x-required-scopes": [ "projects:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 128 }, "description": "Use a unique key for a new create request. Reuse the same key and identical body when retrying that request; do not reuse it for a different operation." } ], "responses": { "201": { "description": "Illustrative success response. IDs and values below are examples; actual responses reflect your authorized records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" }, "example": { "id": "project_example", "version": 1, "name": "Customer service testing", "description": "Example workspace project" } } } }, "429": { "description": "Request limit exceeded. Wait for the interval indicated by Retry-After before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error response. 400: invalid request; 401: missing, expired or invalid token; 403: permission denied; 404: record not available to this token; 409: conflict; 412: stale version; 422: invalid fields; 429: rate limit; 503: temporarily unavailable. Handle the returned code and retain requestId for support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "not_found", "status": 404, "code": "not_found", "detail": "Resource not found.", "requestId": "request_example" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectInput" }, "example": { "name": "Customer service testing", "description": "Example workspace project" } } } }, "description": "Projects organize related Systems and test work within your workspace.\n\nCreate a Project after preparing the required fields. Retain the returned ID for subsequent requests.\n\nSaves configuration only. Does not start discovery, place a call or run a test.\n\nAccess is limited to the workspace and Projects authorized by your API token. IDs do not grant access to another workspace. Use Idempotency-Key to retry safely.", "x-related-operations": [ "createSystem", "listSystems" ], "x-availability": "preview" } }, "/projects/{projectId}": { "get": { "operationId": "getProject", "summary": "Get project", "x-required-scopes": [ "projects:read" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the authorized project. Obtain it from a previous create or list response.", "example": "project_example" } ], "responses": { "200": { "description": "Illustrative success response. IDs and values below are examples; actual responses reflect your authorized records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" }, "example": { "id": "project_example", "version": 1, "name": "Customer service testing", "description": "Example workspace project" } } }, "headers": { "ETag": { "schema": { "type": "string", "maxLength": 4000 }, "description": "Opaque resource version; required as If-Match for updates when resource is versioned." } } }, "429": { "description": "Request limit exceeded. Wait for the interval indicated by Retry-After before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error response. 400: invalid request; 401: missing, expired or invalid token; 403: permission denied; 404: record not available to this token; 409: conflict; 412: stale version; 422: invalid fields; 429: rate limit; 503: temporarily unavailable. Handle the returned code and retain requestId for support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "not_found", "status": 404, "code": "not_found", "detail": "Resource not found.", "requestId": "request_example" } } } } }, "description": "Projects organize related Systems and test work within your workspace.\n\nRetrieve one record by ID to inspect its current content and version.\n\nRead-only. No records or evidence are changed.\n\nAccess is limited to the workspace and Projects authorized by your API token. IDs do not grant access to another workspace.", "x-related-operations": [ "createSystem", "listSystems" ], "x-availability": "preview" }, "patch": { "operationId": "updateProject", "summary": "Update project", "x-required-scopes": [ "projects:write" ], "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the authorized project. Obtain it from a previous create or list response.", "example": "project_example" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Send the ETag from the latest read, including its quotes. If the record changed, read it again before retrying your update.", "example": "\"1\"" } ], "responses": { "200": { "description": "Illustrative success response. IDs and values below are examples; actual responses reflect your authorized records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" }, "example": { "id": "project_example", "version": 1, "name": "Customer service testing", "description": "Example workspace project" } } }, "headers": { "ETag": { "schema": { "type": "string", "maxLength": 4000 }, "description": "Opaque resource version; required as If-Match for updates when resource is versioned." } } }, "429": { "description": "Request limit exceeded. Wait for the interval indicated by Retry-After before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error response. 400: invalid request; 401: missing, expired or invalid token; 403: permission denied; 404: record not available to this token; 409: conflict; 412: stale version; 422: invalid fields; 429: rate limit; 503: temporarily unavailable. Handle the returned code and retain requestId for support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "not_found", "status": 404, "code": "not_found", "detail": "Resource not found.", "requestId": "request_example" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectPatch" }, "example": { "description": "Updated project description" } } } }, "description": "Projects organize related Systems and test work within your workspace.\n\nUpdate an existing record. Send only the fields you want to change; omitted fields remain unchanged.\n\nSaves configuration only. Does not start discovery, place a call or run a test.\n\nAccess is limited to the workspace and Projects authorized by your API token. IDs do not grant access to another workspace. Use If-Match with the current ETag to avoid overwriting a newer change.", "x-related-operations": [ "createSystem", "listSystems" ], "x-availability": "preview" } }, "/systems": { "get": { "operationId": "listSystems", "summary": "List systems", "x-required-scopes": [ "systems:read" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Use nextCursor from the preceding page unchanged. If it expires or the collection changes, restart from the first page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Maximum number of items to return on this page; follow the allowed range in the schema.", "example": 20 } ], "responses": { "200": { "description": "Illustrative success response. IDs and values below are examples; actual responses reflect your authorized records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemPage" }, "example": { "items": [ { "id": "system_example", "version": 1, "projectId": "project_example", "name": "Customer support", "type": "iva" } ], "nextCursor": null, "requestId": "request_example" } } }, "headers": { "ETag": { "schema": { "type": "string", "maxLength": 4000 }, "description": "Opaque resource version; required as If-Match for updates when resource is versioned." } } }, "429": { "description": "Request limit exceeded. Wait for the interval indicated by Retry-After before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error response. 400: invalid request; 401: missing, expired or invalid token; 403: permission denied; 404: record not available to this token; 409: conflict; 412: stale version; 422: invalid fields; 429: rate limit; 503: temporarily unavailable. Handle the returned code and retain requestId for support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "not_found", "status": 404, "code": "not_found", "detail": "Resource not found.", "requestId": "request_example" } } } } }, "description": "A System represents the application or service you want to test and belongs to an authorized Project.\n\nList the records you are permitted to read. Use this to locate IDs for subsequent requests.\n\nRead-only. No records or evidence are changed.\n\nAccess is limited to the workspace and Projects authorized by your API token. IDs do not grant access to another workspace.", "x-related-operations": [ "listConnections", "createConnection", "createPlan" ], "x-availability": "preview" }, "post": { "operationId": "createSystem", "summary": "Create system", "x-required-scopes": [ "systems:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 128 }, "description": "Use a unique key for a new create request. Reuse the same key and identical body when retrying that request; do not reuse it for a different operation." } ], "responses": { "201": { "description": "Illustrative success response. IDs and values below are examples; actual responses reflect your authorized records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/System" }, "example": { "id": "system_example", "version": 1, "projectId": "project_example", "name": "Customer support", "type": "iva" } } } }, "429": { "description": "Request limit exceeded. Wait for the interval indicated by Retry-After before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error response. 400: invalid request; 401: missing, expired or invalid token; 403: permission denied; 404: record not available to this token; 409: conflict; 412: stale version; 422: invalid fields; 429: rate limit; 503: temporarily unavailable. Handle the returned code and retain requestId for support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "not_found", "status": 404, "code": "not_found", "detail": "Resource not found.", "requestId": "request_example" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemInput" }, "example": { "projectId": "project_example", "name": "Customer support", "type": "iva", "description": "Service under test" } } } }, "description": "A System represents the application or service you want to test and belongs to an authorized Project.\n\nCreate a System after preparing the required fields. Retain the returned ID for subsequent requests.\n\nSaves configuration only. Does not start discovery, place a call or run a test.\n\nAccess is limited to the workspace and Projects authorized by your API token. IDs do not grant access to another workspace. Use Idempotency-Key to retry safely.", "x-related-operations": [ "listConnections", "createConnection", "createPlan" ], "x-availability": "preview" } }, "/systems/{systemId}": { "get": { "operationId": "getSystem", "summary": "Get system", "x-required-scopes": [ "systems:read" ], "parameters": [ { "name": "systemId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the authorized system. Obtain it from a previous create or list response.", "example": "system_example" } ], "responses": { "200": { "description": "Illustrative success response. IDs and values below are examples; actual responses reflect your authorized records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/System" }, "example": { "id": "system_example", "version": 1, "projectId": "project_example", "name": "Customer support", "type": "iva" } } }, "headers": { "ETag": { "schema": { "type": "string", "maxLength": 4000 }, "description": "Opaque resource version; required as If-Match for updates when resource is versioned." } } }, "429": { "description": "Request limit exceeded. Wait for the interval indicated by Retry-After before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error response. 400: invalid request; 401: missing, expired or invalid token; 403: permission denied; 404: record not available to this token; 409: conflict; 412: stale version; 422: invalid fields; 429: rate limit; 503: temporarily unavailable. Handle the returned code and retain requestId for support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "not_found", "status": 404, "code": "not_found", "detail": "Resource not found.", "requestId": "request_example" } } } } }, "description": "A System represents the application or service you want to test and belongs to an authorized Project.\n\nRetrieve one record by ID to inspect its current content and version.\n\nRead-only. No records or evidence are changed.\n\nAccess is limited to the workspace and Projects authorized by your API token. IDs do not grant access to another workspace.", "x-related-operations": [ "listConnections", "createConnection", "createPlan" ], "x-availability": "preview" }, "patch": { "operationId": "updateSystem", "summary": "Update system", "x-required-scopes": [ "systems:write" ], "parameters": [ { "name": "systemId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the authorized system. Obtain it from a previous create or list response.", "example": "system_example" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Send the ETag from the latest read, including its quotes. If the record changed, read it again before retrying your update.", "example": "\"1\"" } ], "responses": { "200": { "description": "Illustrative success response. IDs and values below are examples; actual responses reflect your authorized records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/System" }, "example": { "id": "system_example", "version": 1, "projectId": "project_example", "name": "Customer support", "type": "iva" } } }, "headers": { "ETag": { "schema": { "type": "string", "maxLength": 4000 }, "description": "Opaque resource version; required as If-Match for updates when resource is versioned." } } }, "429": { "description": "Request limit exceeded. Wait for the interval indicated by Retry-After before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error response. 400: invalid request; 401: missing, expired or invalid token; 403: permission denied; 404: record not available to this token; 409: conflict; 412: stale version; 422: invalid fields; 429: rate limit; 503: temporarily unavailable. Handle the returned code and retain requestId for support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "not_found", "status": 404, "code": "not_found", "detail": "Resource not found.", "requestId": "request_example" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemPatch" }, "example": { "description": "Updated System description" } } } }, "description": "A System represents the application or service you want to test and belongs to an authorized Project.\n\nUpdate an existing record. Send only the fields you want to change; omitted fields remain unchanged.\n\nSaves configuration only. Does not start discovery, place a call or run a test.\n\nAccess is limited to the workspace and Projects authorized by your API token. IDs do not grant access to another workspace. Use If-Match with the current ETag to avoid overwriting a newer change.", "x-related-operations": [ "listConnections", "createConnection", "createPlan" ], "x-availability": "preview" } }, "/systems/{systemId}/connections": { "post": { "operationId": "createConnection", "summary": "Create connection", "x-required-scopes": [ "systems:write" ], "parameters": [ { "name": "systemId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the authorized system. Obtain it from a previous create or list response.", "example": "system_example" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 128 }, "description": "Use a unique key for a new create request. Reuse the same key and identical body when retrying that request; do not reuse it for a different operation." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 4000 }, "description": "Send the ETag from the latest read, including its quotes. If the record changed, read it again before retrying your update.", "example": "\"1\"" } ], "responses": { "201": { "description": "Illustrative success response. IDs and values below are examples; actual responses reflect your authorized records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" }, "example": { "id": "connection_example", "version": 1, "systemId": "system_example", "name": "Public website", "type": "website", "destination": "https://example.com" } } } }, "429": { "description": "Request limit exceeded. Wait for the interval indicated by Retry-After before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error response. 400: invalid request; 401: missing, expired or invalid token; 403: permission denied; 404: record not available to this token; 409: conflict; 412: stale version; 422: invalid fields; 429: rate limit; 503: temporarily unavailable. Handle the returned code and retain requestId for support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "not_found", "status": 404, "code": "not_found", "detail": "Resource not found.", "requestId": "request_example" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionInput" }, "example": { "name": "Public website", "type": "website", "destination": "https://example.com" } } } }, "description": "Connections describe a phone, website or agent destination. They belong to one System.\n\nCreate a System connection after preparing the required fields. Retain the returned ID for subsequent requests.\n\nSaves configuration only. Does not start discovery, place a call or run a test.\n\nAccess is limited to the workspace and Projects authorized by your API token. IDs do not grant access to another workspace. Use Idempotency-Key to retry safely.", "x-related-operations": [ "getSystem", "createPlan", "createDiscovery" ], "x-availability": "preview" }, "get": { "operationId": "listConnections", "summary": "List connections", "x-required-scopes": [ "systems:read" ], "parameters": [ { "name": "systemId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the authorized system. Obtain it from a previous create or list response.", "example": "system_example" } ], "responses": { "200": { "description": "Illustrative success response. IDs and values below are examples; actual responses reflect your authorized records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionPage" }, "example": { "items": [ { "id": "connection_example", "version": 1, "systemId": "system_example", "name": "Public website", "type": "website", "destination": "https://example.com" } ], "requestId": "request_example" } } }, "headers": { "ETag": { "schema": { "type": "string", "maxLength": 4000 }, "description": "Opaque resource version; required as If-Match for updates when resource is versioned." } } }, "429": { "description": "Request limit exceeded. Wait for the interval indicated by Retry-After before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error response. 400: invalid request; 401: missing, expired or invalid token; 403: permission denied; 404: record not available to this token; 409: conflict; 412: stale version; 422: invalid fields; 429: rate limit; 503: temporarily unavailable. Handle the returned code and retain requestId for support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "not_found", "status": 404, "code": "not_found", "detail": "Resource not found.", "requestId": "request_example" } } } } }, "description": "Connections describe a phone, website or agent destination. They belong to one System.\n\nList the records you are permitted to read. Use this to locate IDs for subsequent requests.\n\nRead-only. No records or evidence are changed.\n\nAccess is limited to the workspace and Projects authorized by your API token. IDs do not grant access to another workspace.", "x-related-operations": [ "getSystem", "createPlan", "createDiscovery" ], "x-availability": "preview" } }, "/discoveries": { "post": { "operationId": "createDiscovery", "summary": "Create discovery", "x-required-scopes": [ "discoveries:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 128 }, "description": "Use a unique key for a new create request. Reuse the same key and identical body when retrying that request; do not reuse it for a different operation." } ], "responses": { "201": { "description": "Illustrative success response. IDs and values below are examples; actual responses reflect your authorized records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Discovery" }, "example": { "id": "discovery_example", "version": 1, "name": "Support information review", "systemId": "system_example", "status": "draft" } } } }, "429": { "description": "Request limit exceeded. Wait for the interval indicated by Retry-After before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error response. 400: invalid request; 401: missing, expired or invalid token; 403: permission denied; 404: record not available to this token; 409: conflict; 412: stale version; 422: invalid fields; 429: rate limit; 503: temporarily unavailable. Handle the returned code and retain requestId for support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "not_found", "status": 404, "code": "not_found", "detail": "Resource not found.", "requestId": "request_example" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoveryInput" }, "example": { "name": "Support information review", "systemId": "system_example", "connectionRef": { "id": "connection_example", "version": 1 }, "objective": "Review available support information from saved evidence.", "interactionLimit": 1 } } } }, "description": "Discovery records capture an objective and System connection, with findings from available saved evidence. This preview does not perform live discovery.\n\nCreate a discovery after preparing the required fields. Retain the returned ID for subsequent requests.\n\nSaves configuration only. Does not start discovery, place a call or run a test.\n\nAccess is limited to the workspace and Projects authorized by your API token. IDs do not grant access to another workspace. Use Idempotency-Key to retry safely.", "x-related-operations": [ "getDiscovery", "createPlan" ], "x-availability": "preview" }, "get": { "operationId": "listDiscoveries", "summary": "List discoveries", "x-required-scopes": [ "discoveries:read" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "A page of authorized discoveries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoveryPage" }, "example": { "items": [], "nextCursor": null, "requestId": "request_example" } } }, "headers": { "ETag": { "schema": { "type": "string", "maxLength": 4000 }, "description": "Opaque resource version; required as If-Match for updates when resource is versioned." } } }, "429": { "description": "Request limit exceeded; retry after indicated seconds. Local quotas are not production or call quotas.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Structured error: 400, 401, 403, 404, 409, 412, 422, 429 or 503 as applicable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "description": "List discoveries visible to your token. Use a discovery ID to reopen its objective and available saved findings. This is read-only and does not start discovery. Results are limited to authorized workspace and Project access.", "x-related-operations": [ "createDiscovery", "getDiscovery" ], "x-availability": "preview" } }, "/discoveries/{discoveryId}": { "get": { "operationId": "getDiscovery", "summary": "Get discovery", "x-required-scopes": [ "discoveries:read" ], "parameters": [ { "name": "discoveryId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the authorized discovery. Obtain it from a previous create or list response.", "example": "discovery_example" } ], "responses": { "200": { "description": "Illustrative success response. IDs and values below are examples; actual responses reflect your authorized records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Discovery" }, "example": { "id": "discovery_example", "version": 1, "name": "Support information review", "systemId": "system_example", "status": "draft" } } }, "headers": { "ETag": { "schema": { "type": "string", "maxLength": 4000 }, "description": "Opaque resource version; required as If-Match for updates when resource is versioned." } } }, "429": { "description": "Request limit exceeded. Wait for the interval indicated by Retry-After before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error response. 400: invalid request; 401: missing, expired or invalid token; 403: permission denied; 404: record not available to this token; 409: conflict; 412: stale version; 422: invalid fields; 429: rate limit; 503: temporarily unavailable. Handle the returned code and retain requestId for support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "not_found", "status": 404, "code": "not_found", "detail": "Resource not found.", "requestId": "request_example" } } } } }, "description": "Discovery records capture an objective and System connection, with findings from available saved evidence. This preview does not perform live discovery.\n\nRetrieve one record by ID to inspect its current content and version.\n\nRead-only. No records or evidence are changed.\n\nAccess is limited to the workspace and Projects authorized by your API token. IDs do not grant access to another workspace.", "x-related-operations": [ "createPlan" ], "x-availability": "preview" } }, "/plans": { "get": { "operationId": "listPlans", "summary": "List plans", "x-required-scopes": [ "plans:read" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Use nextCursor from the preceding page unchanged. If it expires or the collection changes, restart from the first page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Maximum number of items to return on this page; follow the allowed range in the schema.", "example": 20 } ], "responses": { "200": { "description": "Illustrative success response. IDs and values below are examples; actual responses reflect your authorized records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanPage" }, "example": { "items": [ { "id": "plan_example", "version": 1, "name": "Service information", "outcome": "Explain available support options", "systemId": "system_example", "scenarios": [], "planStatus": "draft" } ], "nextCursor": null, "requestId": "request_example" } } }, "headers": { "ETag": { "schema": { "type": "string", "maxLength": 4000 }, "description": "Opaque resource version; required as If-Match for updates when resource is versioned." } } }, "429": { "description": "Request limit exceeded. Wait for the interval indicated by Retry-After before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error response. 400: invalid request; 401: missing, expired or invalid token; 403: permission denied; 404: record not available to this token; 409: conflict; 412: stale version; 422: invalid fields; 429: rate limit; 503: temporarily unavailable. Handle the returned code and retain requestId for support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "not_found", "status": 404, "code": "not_found", "detail": "Resource not found.", "requestId": "request_example" } } } } }, "description": "A plan describes the expected outcome, scenarios and tester guidance. Saving a draft does not run a test.\n\nList the records you are permitted to read. Use this to locate IDs for subsequent requests.\n\nRead-only. No records or evidence are changed.\n\nAccess is limited to the workspace and Projects authorized by your API token. IDs do not grant access to another workspace.", "x-related-operations": [ "getPlan", "getReadiness" ], "x-availability": "preview" }, "post": { "operationId": "createPlan", "summary": "Create plan", "x-required-scopes": [ "plans:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 128 }, "description": "Use a unique key for a new create request. Reuse the same key and identical body when retrying that request; do not reuse it for a different operation." } ], "responses": { "201": { "description": "Illustrative success response. IDs and values below are examples; actual responses reflect your authorized records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" }, "example": { "id": "plan_example", "version": 1, "name": "Service information", "outcome": "Explain available support options", "systemId": "system_example", "scenarios": [], "planStatus": "draft" } } } }, "429": { "description": "Request limit exceeded. Wait for the interval indicated by Retry-After before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error response. 400: invalid request; 401: missing, expired or invalid token; 403: permission denied; 404: record not available to this token; 409: conflict; 412: stale version; 422: invalid fields; 429: rate limit; 503: temporarily unavailable. Handle the returned code and retain requestId for support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "not_found", "status": 404, "code": "not_found", "detail": "Resource not found.", "requestId": "request_example" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanInput" }, "example": { "name": "Service information", "outcome": "Explain available support options", "systemId": "system_example", "scenarios": [ { "name": "Support options", "instructions": "Ask which support channels are available.", "assertions": [ { "type": "manual_review", "expected": "The response explains available support channels.", "source": "Example acceptance requirement", "required": true } ] } ] } } } }, "description": "A plan describes the expected outcome, scenarios and tester guidance. Saving a draft does not run a test.\n\nCreate a test plan draft after preparing the required fields. Retain the returned ID for subsequent requests.\n\nSaves configuration only. Does not start discovery, place a call or run a test.\n\nAccess is limited to the workspace and Projects authorized by your API token. IDs do not grant access to another workspace. Use Idempotency-Key to retry safely.", "x-related-operations": [ "getPlan", "getReadiness" ], "x-availability": "preview" } }, "/plans/{planId}": { "get": { "operationId": "getPlan", "summary": "Get plan", "x-required-scopes": [ "plans:read" ], "parameters": [ { "name": "planId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the authorized plan. Obtain it from a previous create or list response.", "example": "plan_example" } ], "responses": { "200": { "description": "Illustrative success response. IDs and values below are examples; actual responses reflect your authorized records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" }, "example": { "id": "plan_example", "version": 1, "name": "Service information", "outcome": "Explain available support options", "systemId": "system_example", "scenarios": [], "planStatus": "draft" } } }, "headers": { "ETag": { "schema": { "type": "string", "maxLength": 4000 }, "description": "Opaque resource version; required as If-Match for updates when resource is versioned." } } }, "429": { "description": "Request limit exceeded. Wait for the interval indicated by Retry-After before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error response. 400: invalid request; 401: missing, expired or invalid token; 403: permission denied; 404: record not available to this token; 409: conflict; 412: stale version; 422: invalid fields; 429: rate limit; 503: temporarily unavailable. Handle the returned code and retain requestId for support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "not_found", "status": 404, "code": "not_found", "detail": "Resource not found.", "requestId": "request_example" } } } } }, "description": "A plan describes the expected outcome, scenarios and tester guidance. Saving a draft does not run a test.\n\nRetrieve one record by ID to inspect its current content and version.\n\nRead-only. No records or evidence are changed.\n\nAccess is limited to the workspace and Projects authorized by your API token. IDs do not grant access to another workspace.", "x-related-operations": [ "getReadiness" ], "x-availability": "preview" }, "patch": { "operationId": "updatePlan", "summary": "Update plan", "x-required-scopes": [ "plans:write" ], "parameters": [ { "name": "planId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the authorized plan. Obtain it from a previous create or list response.", "example": "plan_example" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Send the ETag from the latest read, including its quotes. If the record changed, read it again before retrying your update.", "example": "\"1\"" } ], "responses": { "200": { "description": "Illustrative success response. IDs and values below are examples; actual responses reflect your authorized records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" }, "example": { "id": "plan_example", "version": 1, "name": "Service information", "outcome": "Explain available support options", "systemId": "system_example", "scenarios": [], "planStatus": "draft" } } }, "headers": { "ETag": { "schema": { "type": "string", "maxLength": 4000 }, "description": "Opaque resource version; required as If-Match for updates when resource is versioned." } } }, "429": { "description": "Request limit exceeded. Wait for the interval indicated by Retry-After before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error response. 400: invalid request; 401: missing, expired or invalid token; 403: permission denied; 404: record not available to this token; 409: conflict; 412: stale version; 422: invalid fields; 429: rate limit; 503: temporarily unavailable. Handle the returned code and retain requestId for support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "not_found", "status": 404, "code": "not_found", "detail": "Resource not found.", "requestId": "request_example" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanPatch" }, "example": { "outcome": "Explain support channels and their availability" } } } }, "description": "A plan describes the expected outcome, scenarios and tester guidance. Saving a draft does not run a test.\n\nUpdate an existing record. Send only the fields you want to change; omitted fields remain unchanged.\n\nSaves configuration only. Does not start discovery, place a call or run a test.\n\nAccess is limited to the workspace and Projects authorized by your API token. IDs do not grant access to another workspace. Use If-Match with the current ETag to avoid overwriting a newer change.", "x-related-operations": [ "getPlan", "getReadiness" ], "x-availability": "preview" } }, "/plans/{planId}/readiness": { "get": { "operationId": "getReadiness", "summary": "Get readiness", "x-required-scopes": [ "plans:read" ], "parameters": [ { "name": "planId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the authorized plan. Obtain it from a previous create or list response.", "example": "plan_example" } ], "responses": { "200": { "description": "Illustrative success response. IDs and values below are examples; actual responses reflect your authorized records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Readiness" }, "example": { "planId": "plan_example", "planVersion": 1, "ready": false, "executionAllowed": false, "issues": [ { "code": "example_missing_configuration", "message": "Complete the required tester guidance." } ], "executionBlockers": [ { "code": "example_execution_unavailable", "message": "Execution is unavailable in this preview." } ] } } } }, "429": { "description": "Request limit exceeded. Wait for the interval indicated by Retry-After before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error response. 400: invalid request; 401: missing, expired or invalid token; 403: permission denied; 404: record not available to this token; 409: conflict; 412: stale version; 422: invalid fields; 429: rate limit; 503: temporarily unavailable. Handle the returned code and retain requestId for support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "not_found", "status": 404, "code": "not_found", "detail": "Resource not found.", "requestId": "request_example" } } } } }, "description": "Check whether a saved plan has the configuration needed for review. Read the issues and execution blockers separately. This operation does not save, approve or start a test; execution is unavailable in this preview.\n\nRead-only. No records or evidence are changed.\n\nAccess is limited to the workspace and Projects authorized by your API token. IDs do not grant access to another workspace.", "x-related-operations": [ "getRun", "getResults", "getTranscript", "listRecordings" ], "x-availability": "preview" } }, "/runs": { "get": { "operationId": "listRuns", "summary": "List saved runs", "x-required-scopes": [ "runs:read" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Use nextCursor from the preceding page unchanged. If it expires or the collection changes, restart from the first page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Maximum number of items to return on this page; follow the allowed range in the schema.", "example": 20 } ], "responses": { "200": { "description": "Illustrative success response. IDs and values below are examples; actual responses reflect your authorized records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunPage" }, "example": { "items": [ { "id": "run_example", "systemId": "system_example", "status": "unknown", "evidenceStatus": "partial" } ], "nextCursor": null, "requestId": "request_example" } } }, "headers": { "ETag": { "schema": { "type": "string", "maxLength": 4000 }, "description": "Opaque resource version; required as If-Match for updates when resource is versioned." } } }, "429": { "description": "Request limit exceeded. Wait for the interval indicated by Retry-After before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error response. 400: invalid request; 401: missing, expired or invalid token; 403: permission denied; 404: record not available to this token; 409: conflict; 412: stale version; 422: invalid fields; 429: rate limit; 503: temporarily unavailable. Handle the returned code and retain requestId for support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "not_found", "status": 404, "code": "not_found", "detail": "Resource not found.", "requestId": "request_example" } } } } }, "description": "List saved runs visible to your token. Use a run ID to retrieve results, transcript or recording metadata. This read-only operation does not start or resume a run.\n\nRead-only. No records or evidence are changed.\n\nAccess is limited to the workspace and Projects authorized by your API token. IDs do not grant access to another workspace.", "x-related-operations": [ "getRun", "getResults", "getTranscript", "listRecordings" ], "x-availability": "preview" } }, "/runs/{runId}": { "get": { "operationId": "getRun", "summary": "Get run", "x-required-scopes": [ "runs:read" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the authorized run. Obtain it from a previous create or list response.", "example": "run_example" } ], "responses": { "200": { "description": "Illustrative success response. IDs and values below are examples; actual responses reflect your authorized records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" }, "example": { "id": "run_example", "systemId": "system_example", "status": "unknown", "evidenceStatus": "partial" } } }, "headers": { "ETag": { "schema": { "type": "string", "maxLength": 4000 }, "description": "Opaque resource version; required as If-Match for updates when resource is versioned." } } }, "429": { "description": "Request limit exceeded. Wait for the interval indicated by Retry-After before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error response. 400: invalid request; 401: missing, expired or invalid token; 403: permission denied; 404: record not available to this token; 409: conflict; 412: stale version; 422: invalid fields; 429: rate limit; 503: temporarily unavailable. Handle the returned code and retain requestId for support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "not_found", "status": 404, "code": "not_found", "detail": "Resource not found.", "requestId": "request_example" } } } } }, "description": "Read the status and evidence availability of one saved run. A completed run does not necessarily have complete evidence or a passing result. Missing timing values remain unknown.\n\nRead-only. No records or evidence are changed.\n\nAccess is limited to the workspace and Projects authorized by your API token. IDs do not grant access to another workspace.", "x-related-operations": [ "getResults", "getTranscript", "listRecordings" ], "x-availability": "preview" } }, "/runs/{runId}/results": { "get": { "operationId": "getResults", "summary": "Get results", "x-required-scopes": [ "evidence:read" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the authorized run. Obtain it from a previous create or list response.", "example": "run_example" } ], "responses": { "200": { "description": "Illustrative success response. IDs and values below are examples; actual responses reflect your authorized records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Results" }, "example": { "runId": "run_example", "version": 1, "verdict": "not_evaluated", "evidenceStatus": "partial", "scenarios": [] } } }, "headers": { "ETag": { "schema": { "type": "string", "maxLength": 4000 }, "description": "Opaque resource version; required as If-Match for updates when resource is versioned." } } }, "429": { "description": "Request limit exceeded. Wait for the interval indicated by Retry-After before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error response. 400: invalid request; 401: missing, expired or invalid token; 403: permission denied; 404: record not available to this token; 409: conflict; 412: stale version; 422: invalid fields; 429: rate limit; 503: temporarily unavailable. Handle the returned code and retain requestId for support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "not_found", "status": 404, "code": "not_found", "detail": "Resource not found.", "requestId": "request_example" } } } } }, "description": "Read the saved evaluation for a run, including its verdict and scenario results. Inconclusive or not_evaluated must not be treated as pass. Reading does not trigger evaluation or modify evidence.\n\nRead-only. No records or evidence are changed.\n\nAccess is limited to the workspace and Projects authorized by your API token. IDs do not grant access to another workspace.", "x-related-operations": [ "getRun", "getTranscript", "listRecordings" ], "x-availability": "preview" } }, "/runs/{runId}/transcript": { "get": { "operationId": "getTranscript", "summary": "Get transcript", "x-required-scopes": [ "evidence:read" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the authorized run. Obtain it from a previous create or list response.", "example": "run_example" }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 4000 }, "description": "Use nextCursor from the preceding page unchanged. If it expires or the collection changes, restart from the first page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Maximum number of items to return on this page; follow the allowed range in the schema.", "example": 20 } ], "responses": { "200": { "description": "Illustrative success response. IDs and values below are examples; actual responses reflect your authorized records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangePage" }, "example": { "items": [ { "id": "exchange_example", "sequence": 0, "speaker": "tester", "text": "What support options are available?", "alignment": "unavailable", "origin": "authored" } ], "nextCursor": null, "requestId": "request_example" } } }, "headers": { "ETag": { "schema": { "type": "string", "maxLength": 4000 }, "description": "Opaque resource version; required as If-Match for updates when resource is versioned." } } }, "429": { "description": "Request limit exceeded. Wait for the interval indicated by Retry-After before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error response. 400: invalid request; 401: missing, expired or invalid token; 403: permission denied; 404: record not available to this token; 409: conflict; 412: stale version; 422: invalid fields; 429: rate limit; 503: temporarily unavailable. Handle the returned code and retain requestId for support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "not_found", "status": 404, "code": "not_found", "detail": "Resource not found.", "requestId": "request_example" } } } } }, "description": "Read transcript exchanges in their saved sequence order. Origin distinguishes authored text from captured speech; alignment may be exact, approximate or unavailable. This does not transcribe audio or change evidence.\n\nRead-only. No records or evidence are changed.\n\nAccess is limited to the workspace and Projects authorized by your API token. IDs do not grant access to another workspace.", "x-related-operations": [ "getRun", "getResults", "listRecordings" ], "x-availability": "preview" } }, "/runs/{runId}/recordings": { "get": { "operationId": "listRecordings", "summary": "List recordings", "x-required-scopes": [ "recordings:read" ], "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the authorized run. Obtain it from a previous create or list response.", "example": "run_example" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Use nextCursor from the preceding page unchanged. If it expires or the collection changes, restart from the first page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Maximum number of items to return on this page; follow the allowed range in the schema.", "example": 20 } ], "responses": { "200": { "description": "Illustrative success response. IDs and values below are examples; actual responses reflect your authorized records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordingPage" }, "example": { "items": [ { "id": "recording_example", "runId": "run_example", "status": "unavailable", "alignment": "unavailable" } ], "nextCursor": null, "requestId": "request_example" } } }, "headers": { "ETag": { "schema": { "type": "string", "maxLength": 4000 }, "description": "Opaque resource version; required as If-Match for updates when resource is versioned." } } }, "429": { "description": "Request limit exceeded. Wait for the interval indicated by Retry-After before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error response. 400: invalid request; 401: missing, expired or invalid token; 403: permission denied; 404: record not available to this token; 409: conflict; 412: stale version; 422: invalid fields; 429: rate limit; 503: temporarily unavailable. Handle the returned code and retain requestId for support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "not_found", "status": 404, "code": "not_found", "detail": "Resource not found.", "requestId": "request_example" } } } } }, "description": "List recording metadata associated with a saved run. Availability and alignment describe the saved record; this endpoint does not return playback URLs or grant audio access.\n\nRead-only. No records or evidence are changed.\n\nAccess is limited to the workspace and Projects authorized by your API token. IDs do not grant access to another workspace.", "x-related-operations": [ "getRun", "getResults", "getTranscript" ], "x-availability": "preview" } }, "/systems/{systemId}/connections/{connectionId}": { "get": { "operationId": "getConnection", "summary": "Get connection", "x-required-scopes": [ "systems:read" ], "parameters": [ { "name": "systemId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the authorized system. Obtain it from a previous create or list response.", "example": "system_example" }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the authorized connection. Obtain it from a previous create or list response.", "example": "connection_example" } ], "responses": { "200": { "description": "Illustrative success response. IDs and values below are examples; actual responses reflect your authorized records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" }, "example": { "id": "connection_example", "version": 1, "systemId": "system_example", "name": "Public website", "type": "website", "destination": "https://example.com" } } }, "headers": { "ETag": { "schema": { "type": "string", "maxLength": 4000 }, "description": "Opaque resource version; required as If-Match for updates when resource is versioned." } } }, "429": { "description": "Request limit exceeded. Wait for the interval indicated by Retry-After before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error response. 400: invalid request; 401: missing, expired or invalid token; 403: permission denied; 404: record not available to this token; 409: conflict; 412: stale version; 422: invalid fields; 429: rate limit; 503: temporarily unavailable. Handle the returned code and retain requestId for support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "not_found", "status": 404, "code": "not_found", "detail": "Resource not found.", "requestId": "request_example" } } } } }, "description": "Connections describe a phone, website or agent destination. They belong to one System.\n\nRetrieve one record by ID to inspect its current content and version.\n\nRead-only. No records or evidence are changed.\n\nAccess is limited to the workspace and Projects authorized by your API token. IDs do not grant access to another workspace.", "x-related-operations": [ "getSystem", "createPlan", "createDiscovery" ], "x-availability": "preview" }, "patch": { "operationId": "updateConnection", "summary": "Update connection", "x-required-scopes": [ "systems:write" ], "parameters": [ { "name": "systemId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the authorized system. Obtain it from a previous create or list response.", "example": "system_example" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Send the ETag from the latest read, including its quotes. If the record changed, read it again before retrying your update.", "example": "\"1\"" }, { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the authorized connection. Obtain it from a previous create or list response.", "example": "connection_example" } ], "responses": { "200": { "description": "Illustrative success response. IDs and values below are examples; actual responses reflect your authorized records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connection" }, "example": { "id": "connection_example", "version": 1, "systemId": "system_example", "name": "Public website", "type": "website", "destination": "https://example.com" } } }, "headers": { "ETag": { "schema": { "type": "string", "maxLength": 4000 }, "description": "Opaque resource version; required as If-Match for updates when resource is versioned." } } }, "429": { "description": "Request limit exceeded. Wait for the interval indicated by Retry-After before retrying.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error response. 400: invalid request; 401: missing, expired or invalid token; 403: permission denied; 404: record not available to this token; 409: conflict; 412: stale version; 422: invalid fields; 429: rate limit; 503: temporarily unavailable. Handle the returned code and retain requestId for support.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "not_found", "status": 404, "code": "not_found", "detail": "Resource not found.", "requestId": "request_example" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionPatch" }, "example": { "name": "Support website" } } } }, "description": "Connections describe a phone, website or agent destination. They belong to one System.\n\nUpdate an existing record. Send only the fields you want to change; omitted fields remain unchanged.\n\nSaves configuration only. Does not start discovery, place a call or run a test.\n\nAccess is limited to the workspace and Projects authorized by your API token. IDs do not grant access to another workspace. Use If-Match with the current ETag to avoid overwriting a newer change.", "x-related-operations": [ "getSystem", "createPlan", "createDiscovery" ], "x-availability": "preview" } } }, "components": { "securitySchemes": { "apiToken": { "type": "http", "scheme": "bearer", "bearerFormat": "Opaque tenant-scoped API token", "description": "Admin-issued; hashed at rest; expires and supports revocation. Never use in query strings." }, "adminSession": { "type": "apiKey", "in": "cookie", "name": "PORTAL_SESSION_COOKIE_TBD", "description": "Design placeholder only. Local implementation uses a trusted resolveAdminSession dependency, default-deny. Actual portal session cookie and CSRF adapter must be mapped before integration; no cookie handler is implemented here." } }, "schemas": { "Reference": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Resource identifier." }, "version": { "type": "integer", "minimum": 1, "description": "Current resource version." } }, "required": [ "id", "version" ] }, "ProjectInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 100, "minLength": 1, "description": "Human-readable name." }, "description": { "type": "string", "maxLength": 500, "description": "Optional description for other users." } }, "required": [ "name" ] }, "Project": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Resource identifier." }, "version": { "type": "integer", "minimum": 1, "description": "Current resource version." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "name": { "type": "string", "maxLength": 100, "description": "Human-readable name." }, "description": { "type": "string", "maxLength": 500, "description": "Optional description for other users." } }, "required": [ "id", "version", "name" ] }, "SystemInput": { "type": "object", "additionalProperties": false, "properties": { "projectId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "ID of the Project containing this resource." }, "name": { "type": "string", "maxLength": 100, "minLength": 1, "description": "Human-readable name." }, "type": { "type": "string", "maxLength": 100, "description": "System type supported by your workspace.", "minLength": 1 }, "description": { "type": "string", "maxLength": 500, "description": "Optional description for other users." } }, "required": [ "projectId", "name", "type" ] }, "System": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Resource identifier." }, "version": { "type": "integer", "minimum": 1, "description": "Current resource version." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "projectId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "ID of the Project containing this resource." }, "name": { "type": "string", "maxLength": 100, "description": "Human-readable name." }, "type": { "type": "string", "maxLength": 100, "description": "System type supported by your workspace." }, "description": { "type": "string", "maxLength": 500, "description": "Optional description for other users." }, "connections": { "type": "array", "items": { "$ref": "#/components/schemas/Connection" }, "maxItems": 100 } }, "required": [ "id", "version", "projectId", "name", "type" ] }, "ConnectionInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 100, "minLength": 1, "description": "Human-readable name." }, "type": { "type": "string", "enum": [ "phone", "website", "agent" ], "minLength": 1 }, "destination": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "Destination appropriate to the connection type." }, "protocol": { "type": "string", "enum": [ "api", "a2a", "mcp" ] }, "phoneCountry": { "type": "string", "maxLength": 2 }, "instructions": { "type": "string", "maxLength": 4000, "description": "Instructions for this connection or scenario." } }, "required": [ "name", "type", "destination" ], "description": "Configure a phone, website or agent destination. Credentials and provider settings are not accepted by this endpoint." }, "Connection": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Resource identifier." }, "version": { "type": "integer", "minimum": 1, "description": "Current resource version." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "name": { "type": "string", "maxLength": 100, "description": "Human-readable name." }, "type": { "type": "string", "enum": [ "phone", "website", "agent" ] }, "destination": { "type": "string", "maxLength": 2048, "description": "Destination appropriate to the connection type." }, "protocol": { "type": "string", "enum": [ "api", "a2a", "mcp" ] }, "phoneCountry": { "type": "string", "maxLength": 2 }, "instructions": { "type": "string", "maxLength": 4000, "description": "Instructions for this connection or scenario." }, "systemId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "ID of the System under test." } }, "required": [ "id", "version", "name", "type", "systemId" ] }, "DiscoveryInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 100, "description": "Human-readable name." }, "systemId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "ID of the System under test." }, "connectionRef": { "$ref": "#/components/schemas/Reference", "description": "Connection ID and version belonging to this System." }, "objective": { "type": "string", "minLength": 10, "maxLength": 4000, "description": "What the discovery should establish." }, "interactionLimit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum interactions configured for this discovery." }, "savedEvidenceRef": { "$ref": "#/components/schemas/Reference", "description": "Reference an existing authorized saved evidence record for this System; do not submit findings." } }, "required": [ "name", "systemId", "connectionRef", "objective", "interactionLimit" ] }, "Discovery": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Resource identifier." }, "version": { "type": "integer", "minimum": 1, "description": "Current resource version." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "name": { "type": "string", "maxLength": 100, "description": "Human-readable name." }, "systemId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "ID of the System under test." }, "connectionRef": { "$ref": "#/components/schemas/Reference", "description": "Connection ID and version belonging to this System." }, "objective": { "type": "string", "minLength": 10, "maxLength": 4000, "description": "What the discovery should establish." }, "interactionLimit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum interactions configured for this discovery." }, "status": { "type": "string", "enum": [ "draft", "ready" ] }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/Finding" }, "maxItems": 100 }, "savedEvidenceRef": { "$ref": "#/components/schemas/Reference" }, "projectId": { "type": "string", "readOnly": true, "description": "ID of the Project containing this resource." }, "evidenceOrigin": { "type": "string", "enum": [ "saved_evidence" ] } }, "required": [ "id", "version", "systemId", "name", "status" ] }, "Finding": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Resource identifier." }, "summary": { "type": "string", "maxLength": 4000 }, "sourceUrl": { "type": "string", "format": "uri" }, "capturedAt": { "type": "string", "format": "date-time" }, "evidenceIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 100 } }, "required": [ "id", "summary", "evidenceIds" ] }, "Assertion": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Resource identifier." }, "type": { "type": "string", "enum": [ "manual_review", "exact_wording", "response_contains", "response_outcome", "routing_equals", "duration_max", "backend_equals", "prohibited_action" ], "minLength": 1 }, "expected": { "type": "string", "maxLength": 500, "minLength": 1, "description": "Expected behavior or wording." }, "source": { "type": "string", "maxLength": 300, "minLength": 1, "description": "Source of this requirement." }, "required": { "type": "boolean", "description": "Whether this check is required." }, "severity": { "type": "string", "enum": [ "unclassified", "low", "medium", "high", "critical" ] } }, "required": [ "type", "expected", "source", "required" ] }, "Scenario": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Resource identifier." }, "name": { "type": "string", "maxLength": 100, "minLength": 1, "description": "Human-readable name." }, "instructions": { "type": "string", "maxLength": 1000, "minLength": 1, "description": "Instructions for this connection or scenario." }, "assertions": { "type": "array", "items": { "$ref": "#/components/schemas/Assertion" }, "maxItems": 10 } }, "required": [ "name", "instructions", "assertions" ] }, "Tester": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 100, "description": "Human-readable name." }, "role": { "type": "string", "maxLength": 1000 }, "tone": { "type": "string", "maxLength": 200 }, "language": { "type": "string", "maxLength": 100 }, "openingMessage": { "type": "string", "maxLength": 1000 }, "successCriteria": { "type": "string", "maxLength": 2000 }, "stopConditions": { "type": "string", "maxLength": 1000 }, "prohibitedActions": { "type": "string", "maxLength": 1000 } }, "required": [] }, "Limits": { "type": "object", "additionalProperties": false, "properties": { "maxTurns": { "type": "integer", "minimum": 1, "maximum": 50 }, "maxDurationSeconds": { "type": "integer", "minimum": 10, "maximum": 600 } }, "required": [ "maxTurns", "maxDurationSeconds" ], "description": "Explicit preparation limits. Readiness may report stricter execution requirements. These values do not authorize execution." }, "PlanInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 100, "minLength": 1, "description": "Human-readable name." }, "outcome": { "type": "string", "maxLength": 4000, "minLength": 1, "description": "The result the test should demonstrate." }, "systemId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "ID of the System under test." }, "connectionRef": { "$ref": "#/components/schemas/Reference", "description": "Reference a connection belonging to the selected System, using its current version. Optional for unconfigured drafts. Stale versions reject draft writes with 409; saved drafts remain unchanged." }, "scenarios": { "type": "array", "items": { "$ref": "#/components/schemas/Scenario" }, "maxItems": 10, "description": "Scenarios with instructions and expected outcomes." }, "tester": { "$ref": "#/components/schemas/Tester", "description": "Persona and guidance for the test caller." }, "limits": { "$ref": "#/components/schemas/Limits", "description": "Explicit duration and interaction limits." }, "testDataRef": { "$ref": "#/components/schemas/Reference", "description": "Not available in this preview; omit this field." }, "sourceDiscoveryRef": { "$ref": "#/components/schemas/Reference", "description": "Not available in this preview; omit this field." } }, "required": [ "name", "outcome", "systemId", "scenarios" ], "description": "Saves a draft without starting a test. A connection can be selected using its current ID and version. Test-data and source-discovery references are not available in this preview." }, "Plan": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Resource identifier." }, "version": { "type": "integer", "minimum": 1, "description": "Current resource version." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "name": { "type": "string", "maxLength": 100, "description": "Human-readable name." }, "outcome": { "type": "string", "maxLength": 4000, "description": "The result the test should demonstrate." }, "systemId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "ID of the System under test." }, "connectionRef": { "$ref": "#/components/schemas/Reference", "description": "Connection ID and version belonging to this System." }, "scenarios": { "type": "array", "items": { "$ref": "#/components/schemas/Scenario" }, "maxItems": 10, "description": "Scenarios with instructions and expected outcomes." }, "tester": { "$ref": "#/components/schemas/Tester", "description": "Persona and guidance for the test caller." }, "limits": { "$ref": "#/components/schemas/Limits", "description": "Explicit duration and interaction limits." }, "testDataRef": { "$ref": "#/components/schemas/Reference" }, "sourceDiscoveryRef": { "$ref": "#/components/schemas/Reference" }, "planStatus": { "type": "string", "enum": [ "draft", "ready" ] }, "latestRunId": { "type": "string", "minLength": 1, "maxLength": 200 }, "latestRunResult": { "type": "string", "enum": [ "pass", "fail", "inconclusive", "not_evaluated" ] }, "projectId": { "type": "string", "readOnly": true, "description": "Derived from the authorized System." } }, "required": [ "id", "version", "name", "systemId", "scenarios", "planStatus" ] }, "Issue": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string", "maxLength": 100 }, "field": { "type": "string", "maxLength": 200 }, "message": { "type": "string", "maxLength": 4000 }, "scenarioId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "code", "message" ] }, "Readiness": { "type": "object", "additionalProperties": false, "properties": { "planId": { "type": "string", "minLength": 1, "maxLength": 200 }, "planVersion": { "type": "integer", "minimum": 1 }, "ready": { "type": "boolean" }, "executionAllowed": { "type": "boolean" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/Issue" }, "maxItems": 100 }, "executionBlockers": { "type": "array", "items": { "$ref": "#/components/schemas/Issue" }, "maxItems": 100 }, "preparationStatus": { "type": "string", "enum": [ "Draft", "Ready for review" ], "description": "Preparation only; never execution authorization." }, "reviewNotes": { "type": "array", "items": { "type": "string" }, "description": "Shared portal review guidance. No private test-input values are returned." } }, "required": [ "planId", "planVersion", "ready", "executionAllowed", "issues", "executionBlockers" ] }, "Run": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Resource identifier." }, "planRef": { "$ref": "#/components/schemas/Reference" }, "systemId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "ID of the System under test." }, "connectionRef": { "$ref": "#/components/schemas/Reference", "description": "Connection ID and version belonging to this System." }, "status": { "type": "string", "enum": [ "queued", "preparing", "dialing", "running", "stop_requested", "stopped", "completed", "failed", "unknown" ] }, "evidenceStatus": { "type": "string", "enum": [ "pending", "partial", "complete", "unavailable" ] }, "startedAt": { "type": "string", "format": "date-time" }, "answeredAt": { "type": "string", "format": "date-time" }, "endedAt": { "type": "string", "format": "date-time" }, "talkTimeSeconds": { "type": "number", "minimum": 0 }, "stopReason": { "type": "string", "maxLength": 500 }, "projectId": { "type": "string", "readOnly": true, "description": "ID of the Project containing this resource." }, "kind": { "type": "string", "enum": [ "live-test", "transcript-replay", "imported-recording" ], "description": "Saved record category; does not establish telephone execution." }, "captureClosed": { "type": "boolean", "description": "Whether saved capture reports closure; separate from execution and outcome." }, "replayOfRunId": { "type": "string", "maxLength": 200, "description": "Original run reference when available in the same authorized System." } }, "required": [ "id", "status", "evidenceStatus", "systemId" ] }, "ScenarioResult": { "type": "object", "additionalProperties": false, "properties": { "scenarioId": { "type": "string", "minLength": 1, "maxLength": 200 }, "completion": { "type": "string", "enum": [ "not_started", "in_progress", "completed", "interrupted", "unknown" ] }, "verdict": { "type": "string", "enum": [ "pass", "fail", "inconclusive", "not_evaluated" ] }, "reason": { "type": "string", "maxLength": 4000 }, "evidenceIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 100 }, "scenarioIndex": { "type": "integer", "minimum": 0, "description": "Saved zero-based scenario index for legacy records without an ID." }, "name": { "type": "string", "maxLength": 4000 }, "completionReported": { "type": "boolean", "description": "Saved callback reported completion; does not independently verify it." }, "evidenceReferences": { "type": "array", "maxItems": 1000, "items": { "type": "string", "maxLength": 200 } } }, "required": [ "completion", "verdict", "reason", "evidenceIds" ] }, "Results": { "type": "object", "additionalProperties": false, "properties": { "runId": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "integer", "minimum": 1, "description": "Current resource version." }, "verdict": { "type": "string", "enum": [ "pass", "fail", "inconclusive", "not_evaluated" ] }, "evidenceStatus": { "type": "string", "enum": [ "pending", "partial", "complete", "unavailable" ] }, "scenarios": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioResult" }, "maxItems": 100, "description": "Scenarios with instructions and expected outcomes." }, "evaluatedAt": { "type": "string", "format": "date-time" } }, "required": [ "runId", "version", "verdict", "evidenceStatus", "scenarios" ] }, "Exchange": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Saved exchange ID when present. Legacy entries are addressed by sequence within this run." }, "sequence": { "type": "integer", "minimum": 0 }, "speaker": { "type": "string", "enum": [ "tester", "target", "system", "unknown" ] }, "text": { "type": "string", "maxLength": 16000 }, "occurredAt": { "type": "string", "format": "date-time" }, "recordingId": { "type": "string", "minLength": 1, "maxLength": 200 }, "startOffsetMs": { "type": "number", "minimum": 0 }, "endOffsetMs": { "type": "number", "minimum": 0 }, "alignment": { "type": "string", "enum": [ "exact", "approximate", "unavailable" ] }, "scenarioId": { "type": "string", "minLength": 1, "maxLength": 200 }, "origin": { "type": "string", "enum": [ "authored", "captured", "unknown" ], "description": "Authored text is distinct from captured speech; unknown means provenance is unavailable." }, "scenarioIndex": { "type": "integer", "minimum": 0 } }, "required": [ "sequence", "speaker", "text", "alignment" ] }, "Recording": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Resource identifier." }, "runId": { "type": "string", "minLength": 1, "maxLength": 200 }, "durationMs": { "type": "number", "minimum": 0 }, "status": { "type": "string", "enum": [ "pending", "available", "unavailable" ] }, "contentType": { "type": "string", "maxLength": 100 }, "alignment": { "type": "string", "enum": [ "exact", "approximate", "unavailable" ] } }, "required": [ "id", "runId", "status", "alignment" ] }, "Problem": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string", "maxLength": 200 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "code": { "type": "string", "maxLength": 100 }, "detail": { "type": "string", "maxLength": 4000 }, "requestId": { "type": "string", "minLength": 1, "maxLength": 200 }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/Issue" }, "maxItems": 100 } }, "required": [ "type", "title", "status", "code", "requestId" ] }, "ProjectPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Project" }, "maxItems": 100 }, "nextCursor": { "type": [ "string", "null" ] }, "requestId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "items", "nextCursor", "requestId" ] }, "SystemPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/System" }, "maxItems": 100 }, "nextCursor": { "type": [ "string", "null" ] }, "requestId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "items", "nextCursor", "requestId" ] }, "PlanPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" }, "maxItems": 100 }, "nextCursor": { "type": [ "string", "null" ] }, "requestId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "items", "nextCursor", "requestId" ] }, "ExchangePage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Exchange" }, "maxItems": 100 }, "nextCursor": { "type": [ "string", "null" ] }, "requestId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "items", "nextCursor", "requestId" ] }, "RecordingPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Recording" }, "maxItems": 100 }, "nextCursor": { "type": [ "string", "null" ] }, "requestId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "items", "nextCursor", "requestId" ] }, "ProjectPatch": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 100, "description": "Human-readable name." }, "description": { "type": "string", "maxLength": 500, "description": "Optional description for other users." } }, "required": [], "minProperties": 1 }, "SystemPatch": { "type": "object", "additionalProperties": false, "properties": { "projectId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "ID of the Project containing this resource." }, "name": { "type": "string", "maxLength": 100, "description": "Human-readable name." }, "type": { "type": "string", "maxLength": 100, "description": "System type supported by your workspace." }, "description": { "type": "string", "maxLength": 500, "description": "Optional description for other users." } }, "required": [], "minProperties": 1 }, "PlanPatch": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 100, "minLength": 1, "description": "Human-readable name." }, "outcome": { "type": "string", "maxLength": 4000, "minLength": 1, "description": "The result the test should demonstrate." }, "systemId": { "type": "string", "minLength": 1, "maxLength": 200, "description": "ID of the System under test." }, "connectionRef": { "$ref": "#/components/schemas/Reference", "description": "Reference a connection belonging to the selected System, using its current version. Optional for unconfigured drafts. Stale versions reject draft writes with 409; saved drafts remain unchanged." }, "scenarios": { "type": "array", "items": { "$ref": "#/components/schemas/Scenario" }, "maxItems": 10, "description": "Scenarios with instructions and expected outcomes." }, "tester": { "$ref": "#/components/schemas/Tester", "description": "Persona and guidance for the test caller." }, "limits": { "$ref": "#/components/schemas/Limits", "description": "Explicit duration and interaction limits." }, "testDataRef": { "$ref": "#/components/schemas/Reference", "description": "Not available in this preview; omit this field." }, "sourceDiscoveryRef": { "$ref": "#/components/schemas/Reference", "description": "Not available in this preview; omit this field." } }, "required": [], "minProperties": 1 }, "ConnectionPatch": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 100, "minLength": 1, "description": "Human-readable name." }, "type": { "type": "string", "enum": [ "phone", "website", "agent" ], "minLength": 1 }, "destination": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "Destination appropriate to the connection type." }, "protocol": { "type": "string", "enum": [ "api", "a2a", "mcp" ] }, "phoneCountry": { "type": "string", "maxLength": 2 }, "instructions": { "type": "string", "maxLength": 4000, "description": "Instructions for this connection or scenario." } }, "required": [], "description": "Update the allowed connection fields. Credentials and provider settings are not accepted.", "minProperties": 1 }, "ConnectionPage": { "type": "object", "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/Connection" } }, "requestId": { "type": "string" } }, "required": [ "items", "requestId" ] }, "DiscoveryPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Discovery" }, "maxItems": 100 }, "nextCursor": { "type": [ "string", "null" ] }, "requestId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "items", "nextCursor", "requestId" ] }, "RunPage": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Run" }, "maxItems": 100 }, "nextCursor": { "type": [ "string", "null" ] }, "requestId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "items", "nextCursor", "requestId" ] } } } }