> ## Documentation Index > Fetch the complete documentation index at: https://docs.trusys.ai/llms.txt > Use this file to discover all available pages before exploring further. # Submit traces for evaluation > Scores one or more prompt/response traces against the monitoring configuration on the application. **Prerequisites:** monitoring must include at least one metric or security plugin (`PUT /applications/{applicationId}/monitoring`). **Trace payload:** each trace includes `prompt` and `response` strings. Optional `trusys` metadata supports agentic flows (`tool_calls`, `agent_calls`, `plan`) and retrieval-augmented flows (`query`, `context`). **Single vs batch:** pass `traces` as one object or an array. For a single trace, the response `data` is one object; for a batch, `data` is an array. **Trace IDs:** supply `traceId` (string) to correlate with your own logging, or omit it and one is generated automatically. ## OpenAPI ````yaml /openapi.json post /applications/{applicationId}/evaluations openapi: 3.0.0 info: title: Trusys API version: 1.0.0 description: >- Programmatic access to Trusys for integrating AI quality monitoring, evaluation, and guardrails into your own systems — without using the Trusys UI. **Typical integration flow** 1. `POST /applications` — register your application and get an id. 2. `PUT /applications/{id}/monitoring` and/or `PUT /applications/{id}/guardrails` — configure which metrics, security plugins, and guardrails apply. 3. `POST /applications/{id}/evaluations` — submit prompt/response traces to be scored as your application runs. 4. `GET /applications/{id}/traces`, `GET /applications/{id}/evaluations`, and `POST /applications/{id}/widget-data` — pull results, trends, and dashboard-equivalent chart data back into your own tools. All requests require an `x-api-key` header (see Authentication). All timestamps are ISO 8601 UTC. Paginated endpoints default to 20 items per page (max 100). servers: - url: https://app.trusys.ai/api/external security: - ApiKeyAuth: [] paths: /applications/{applicationId}/evaluations: post: tags: - Evaluations summary: Submit traces for evaluation description: >- Scores one or more prompt/response traces against the monitoring configuration on the application. **Prerequisites:** monitoring must include at least one metric or security plugin (`PUT /applications/{applicationId}/monitoring`). **Trace payload:** each trace includes `prompt` and `response` strings. Optional `trusys` metadata supports agentic flows (`tool_calls`, `agent_calls`, `plan`) and retrieval-augmented flows (`query`, `context`). **Single vs batch:** pass `traces` as one object or an array. For a single trace, the response `data` is one object; for a batch, `data` is an array. **Trace IDs:** supply `traceId` (string) to correlate with your own logging, or omit it and one is generated automatically. operationId: triggerEvaluation parameters: - $ref: '#/components/parameters/applicationId' requestBody: required: true description: One trace or an array of traces to evaluate. content: application/json: schema: $ref: '#/components/schemas/TriggerEvaluationRequest' examples: singleTrace: summary: Agentic trace (weather tool call) description: A single turn with tool-call metadata for agentic metrics. value: traces: prompt: What is the weather in Seattle? response: It is 62°F and cloudy in Seattle. trusys: tool_calls: - name: get_weather description: Fetch current weather for a city arguments: city: Seattle output: 62°F, cloudy batchTraces: summary: Batch RAG traces description: >- Multiple traces with retrieval query and context for RAG metrics. value: traces: - prompt: How many PTO days do employees get? response: Employees receive 20 PTO days per year. trusys: query: PTO allowance context: >- Section 4.2: Full-time employees accrue 20 days of paid time off annually. - prompt: What is the refund policy? response: Refunds are accepted within 30 days of purchase. trusys: query: refund window context: >- Returns and refunds: Customers may request a full refund within 30 calendar days. responses: '200': description: Evaluation completed (or skipped for empty prompt/response pairs). content: application/json: schema: $ref: '#/components/schemas/TriggerEvaluationResponse' examples: single: summary: Single trace result value: success: true data: evalId: f47ac10b-58cc-4372-a567-0e02b2c3d479 applicationId: 550e8400-e29b-41d4-a716-446655440000 traceId: 6ba7b810-9dad-11d1-80b4-00c04fd430c8 batch: summary: Batch result value: success: true data: - evalId: f47ac10b-58cc-4372-a567-0e02b2c3d479 applicationId: 550e8400-e29b-41d4-a716-446655440000 traceId: 6ba7b810-9dad-11d1-80b4-00c04fd430c8 - evalId: a1b2c3d4-e5f6-4789-a012-3456789abcde applicationId: 550e8400-e29b-41d4-a716-446655440000 traceId: b2c3d4e5-f6a7-4890-b123-456789abcdef '400': description: >- Validation error, missing monitoring configuration, or plan restriction. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validation: summary: Invalid body value: success: false message: Invalid request body errors: - path: traces message: Required noMonitoring: summary: Monitoring not configured value: success: false message: No metrics or plugins configured for this application lowCredits: summary: Insufficient credits value: success: false message: >- Your account credits balance is empty. Add credits to continue. '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' components: parameters: applicationId: name: applicationId in: path required: true schema: type: string format: uuid description: >- Unique identifier (UUID) of the application. Returned by `POST /applications`. schemas: TriggerEvaluationRequest: type: object additionalProperties: false required: - traces properties: traces: description: One trace object or a non-empty array of traces. oneOf: - $ref: '#/components/schemas/ExternalTraceItem' - type: array items: $ref: '#/components/schemas/ExternalTraceItem' minItems: 1 TriggerEvaluationResponse: type: object properties: success: type: boolean data: description: >- Single result object for one trace, or an array for batch submissions. oneOf: - type: object properties: evalId: type: string description: Trusys evaluation record ID. applicationId: type: string format: uuid traceId: type: string description: Trace correlation ID (client-supplied or Trusys-generated). skipped: type: boolean description: True if evaluation was skipped (empty prompt and response). reason: type: string description: Why the trace was skipped, when applicable. - type: array items: type: object properties: evalId: type: string applicationId: type: string format: uuid traceId: type: string skipped: type: boolean reason: type: string ErrorResponse: type: object description: Standard error envelope for non-validation failures. properties: success: type: boolean example: false description: Always `false` for errors. message: type: string description: Human-readable explanation of the error. required: - success - message ExternalTraceItem: type: object description: >- A single prompt/response turn to evaluate. At least one of prompt, response, or trusys should be provided. properties: traceId: type: string description: >- Optional correlation ID from your system (any string). Generated by Trusys if omitted. prompt: type: string description: User or system input presented to the model. response: type: string description: Model or assistant output to score. trusys: $ref: '#/components/schemas/ExternalTrusys' ExternalTrusys: type: object description: >- Optional structured metadata for agentic and retrieval-augmented evaluations. Used when running agentic and retrieval-aware metrics. properties: tool_calls: type: array description: Tools invoked during the turn (name, arguments, output). items: type: object agent_calls: type: array description: >- Multi-agent call hierarchy; preferred over tool_calls when both are present. items: type: object plan: type: array items: type: string description: Agent plan steps (ordered list of strings). query: type: string description: Retrieval query sent to a vector store or search (RAG). context: type: string description: Retrieved context chunks passed to the model (RAG). responses: Unauthorized: description: >- The API key is missing, invalid, or revoked. Verify the `x-api-key` header and that the key is active in Trusys settings. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: Error while verifying api key NotFound: description: The requested resource does not exist, or your API key cannot access it. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false message: Application not found securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Your Trusys API key. Create and manage keys in the Trusys UI under **Settings → API Keys**. Include the key on every request: ``` x-api-key: ``` ````