spec.yaml

components:
  schemas:
    AssistantMessage:
      additionalProperties: false
      properties:
        Contents:
          items:
            description: Represents a part of a completion message.
            oneOf:
              - $ref: "#/components/schemas/TextPart"
              - $ref: "#/components/schemas/DataPart"
            type: object
          type:
            - array
            - "null"
        Name:
          type: string
        Role:
          enum:
            - assistant
          type: string
        ToolCalls:
          items:
            $ref: "#/components/schemas/ToolCall"
          type:
            - array
            - "null"
      required:
        - Role
        - Contents
      type: object
    ChatInput:
      additionalProperties: false
      properties:
        Messages:
          items:
            description: Represents a completion message.
            discriminator:
              mapping:
                assistant: "#/components/schemas/AssistantMessage"
                system: "#/components/schemas/SystemMessage"
                tool: "#/components/schemas/ToolMessage"
                user: "#/components/schemas/UserMessage"
              propertyName: Role
            oneOf:
              - $ref: "#/components/schemas/SystemMessage"
              - $ref: "#/components/schemas/UserMessage"
              - $ref: "#/components/schemas/AssistantMessage"
              - $ref: "#/components/schemas/ToolMessage"
            type: object
          type:
            - array
            - "null"
      required:
        - Messages
      type: object
    CheckPayloadRequestBody:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
            - http://api.modelmetry.com//schemas/CheckPayloadRequestBody.json
          format: uri
          readOnly: true
          type: string
        GuardrailID:
          type: string
        Payload:
          $ref: "#/components/schemas/Payload"
        TenantID:
          type: string
      required:
        - GuardrailID
        - Payload
      type: object
    CompletionFamilyData:
      additionalProperties: false
      properties:
        Cost:
          $ref: "#/components/schemas/Cost"
        Documents:
          items:
            $ref: "#/components/schemas/Document"
          type: array
        Input:
          description: Input for completion
          oneOf:
            - $ref: "#/components/schemas/TextInput"
            - $ref: "#/components/schemas/ChatInput"
          type: object
        Options:
          $ref: "#/components/schemas/Options"
        Output:
          $ref: "#/components/schemas/Output"
        Usage:
          $ref: "#/components/schemas/Usage"
      type: object
    Cost:
      additionalProperties: false
      properties:
        Input:
          $ref: "#/components/schemas/Money"
        Output:
          $ref: "#/components/schemas/Money"
        Total:
          $ref: "#/components/schemas/Money"
      type: object
    CreateEventParams:
      additionalProperties: false
      properties:
        At:
          format: date-time
          type:
            - string
            - "null"
        EntryID:
          type:
            - string
            - "null"
        Metadata:
          additionalProperties: {}
          type: object
        Name:
          type: string
        SpanID:
          type:
            - string
            - "null"
        TraceID:
          type:
            - string
            - "null"
        XID:
          type: string
      required:
        - XID
        - Name
      type: object
    CreateFindingParams:
      additionalProperties: false
      properties:
        At:
          format: date-time
          type:
            - string
            - "null"
        Comment:
          type:
            - string
            - "null"
        Description:
          type:
            - string
            - "null"
        EntryID:
          type:
            - string
            - "null"
        Metadata:
          additionalProperties: {}
          type: object
        Name:
          type: string
        Source:
          default: annotation
          enum:
            - annotation
            - evaluator
            - sdk
          type:
            - string
            - "null"
        SpanID:
          type:
            - string
            - "null"
        TraceID:
          type:
            - string
            - "null"
        Value:
          oneOf:
            - type: number
            - type: boolean
            - type: string
            - properties:
                Unit:
                  type: string
                Value:
                  type: number
              required:
                - Value
                - Unit
              type: object
        XID:
          type: string
      required:
        - XID
        - Name
        - Value
      type: object
    CreateSessionParams:
      additionalProperties: false
      properties:
        Metadata:
          additionalProperties: {}
          type: object
        Name:
          type:
            - string
            - "null"
        XID:
          type: string
      required:
        - XID
      type: object
    CreateSpanParams:
      additionalProperties: false
      properties:
        End:
          format: date-time
          type:
            - string
            - "null"
        Family:
          type:
            - string
            - "null"
        FamilyData: {}
        Message:
          type:
            - string
            - "null"
        Metadata:
          additionalProperties: {}
          type: object
        Name:
          type: string
        ParentID:
          type:
            - string
            - "null"
        Severity:
          type:
            - string
            - "null"
        Start:
          format: date-time
          type: string
        TraceID:
          type: string
        XID:
          type: string
      required:
        - TraceID
        - XID
        - Name
        - Start
        - End
      type: object
    CreateTraceParams:
      additionalProperties: false
      properties:
        End:
          format: date-time
          type:
            - string
            - "null"
        Metadata:
          additionalProperties: {}
          type: object
        Name:
          type:
            - string
            - "null"
        SessionID:
          type:
            - string
            - "null"
        Start:
          format: date-time
          type: string
        XID:
          type: string
      required:
        - XID
        - Start
      type: object
    DataPart:
      additionalProperties: false
      properties:
        Detail:
          enum:
            - auto
            - low
            - high
          type: string
        MimeType:
          type: string
        URI:
          type: string
      required:
        - MimeType
        - URI
      type: object
    Document:
      additionalProperties: false
      properties:
        Content: {}
        ContentType:
          type: string
        Identifier:
          type: string
        Metadata:
          additionalProperties: {}
          type: object
        Title:
          type: string
      required:
        - Identifier
        - Title
        - ContentType
      type: object
    EmbeddingsFamilyData:
      additionalProperties: false
      properties:
        Inputs:
          items:
            type: string
          type:
            - array
            - "null"
        Options:
          $ref: "#/components/schemas/Options"
      required:
        - Inputs
        - Options
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    ErrorModel:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
            - http://api.modelmetry.com//schemas/ErrorModel.json
          format: uri
          readOnly: true
          type: string
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          examples:
            - Property foo is required but is missing.
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: "#/components/schemas/ErrorDetail"
          type:
            - array
            - "null"
        instance:
          description: A URI reference that identifies the specific occurrence of the problem.
          examples:
            - https://example.com/error-log/abc123
          format: uri
          type: string
        status:
          description: HTTP status code
          examples:
            - 400
          format: int64
          type: integer
        title:
          description: A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
          examples:
            - Bad Request
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
            - https://example.com/errors/example
          format: uri
          type: string
      type: object
    Event:
      additionalProperties: false
      properties:
        At:
          format: date-time
          type: string
        CreatedAt:
          format: date-time
          type: string
        EntryID:
          type:
            - string
            - "null"
        ID:
          type: string
        Metadata:
          additionalProperties: {}
          type: object
        Name:
          type: string
        SpanID:
          type:
            - string
            - "null"
        TenantID:
          type: string
        TraceID:
          type:
            - string
            - "null"
        UpdatedAt:
          format: date-time
          type: string
        XID:
          type: string
      required:
        - ID
        - XID
        - TenantID
        - Name
        - Metadata
        - At
        - UpdatedAt
        - CreatedAt
        - TraceID
        - SpanID
        - EntryID
      type: object
    Finding:
      additionalProperties: false
      properties:
        At:
          format: date-time
          type: string
        CheckID:
          type: string
        Comment:
          type: string
        CreatedAt:
          format: date-time
          type: string
        EntryID:
          type: string
        EvaluatorID:
          type:
            - string
            - "null"
        ID:
          type: string
        Metadata:
          additionalProperties: {}
          type: object
        Name:
          type: string
        Source:
          default: annotation
          enum:
            - annotation
            - evaluator
            - sdk
          type: string
        SpanID:
          type: string
        TenantID:
          type: string
        TraceID:
          type: string
        UpdatedAt:
          format: date-time
          type: string
        Value:
          oneOf:
            - type: number
            - type: boolean
            - type: string
            - properties:
                Unit:
                  type: string
                Value:
                  type: number
              required:
                - Value
                - Unit
              type: object
        XID:
          type: string
      required:
        - ID
        - XID
        - Name
        - TenantID
        - Value
        - Source
        - Comment
        - Metadata
        - EvaluatorID
        - At
        - UpdatedAt
        - CreatedAt
      type: object
    FullTrace:
      additionalProperties: false
      properties:
        CreatedAt:
          format: date-time
          type: string
        End:
          format: date-time
          type: string
        Events:
          items:
            $ref: "#/components/schemas/Event"
          type:
            - array
            - "null"
        Findings:
          items:
            $ref: "#/components/schemas/Finding"
          type:
            - array
            - "null"
        ID:
          type: string
        Metadata:
          additionalProperties: {}
          type: object
        Name:
          type: string
        SessionID:
          type:
            - string
            - "null"
        Spans:
          items:
            $ref: "#/components/schemas/Span"
          type:
            - array
            - "null"
        Start:
          format: date-time
          type: string
        TenantID:
          type: string
        UpdatedAt:
          format: date-time
          type: string
        XID:
          type: string
      required:
        - Spans
        - Events
        - Findings
        - ID
        - XID
        - TenantID
        - Name
        - Start
        - End
        - Metadata
        - UpdatedAt
        - CreatedAt
      type: object
    Function:
      additionalProperties: false
      properties:
        Arguments: {}
        Name:
          type: string
      required:
        - Name
        - Arguments
      type: object
    GuardrailCheck:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
            - http://api.modelmetry.com//schemas/GuardrailCheck.json
          format: uri
          readOnly: true
          type: string
        CreatedAt:
          format: date-time
          type: string
        CreatedBy:
          type: string
        DurationMs:
          format: int64
          type: integer
        GuardrailID:
          type: string
        ID:
          type: string
        Metadata:
          additionalProperties: {}
          type: object
        Outcome:
          enum:
            - pass
            - fail
            - error
          type: string
        Payload:
          $ref: "#/components/schemas/Payload"
        SummarisedEntries:
          items:
            $ref: "#/components/schemas/SummarisedEntry"
          type:
            - array
            - "null"
        TenantID:
          type: string
        UpdatedAt:
          format: date-time
          type: string
        UpdatedBy:
          type: string
      required:
        - ID
        - TenantID
        - GuardrailID
        - Payload
        - Outcome
        - Metadata
        - SummarisedEntries
        - DurationMs
        - UpdatedAt
        - UpdatedBy
        - CreatedAt
        - CreatedBy
      type: object
    IngestSignalsV1RequestBody:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
            - http://api.modelmetry.com//schemas/IngestSignalsV1RequestBody.json
          format: uri
          readOnly: true
          type: string
        Events:
          items:
            $ref: "#/components/schemas/CreateEventParams"
          type:
            - array
            - "null"
        Findings:
          items:
            $ref: "#/components/schemas/CreateFindingParams"
          type:
            - array
            - "null"
        Sessions:
          items:
            $ref: "#/components/schemas/CreateSessionParams"
          type:
            - array
            - "null"
        Spans:
          items:
            $ref: "#/components/schemas/CreateSpanParams"
          type:
            - array
            - "null"
        Traces:
          items:
            $ref: "#/components/schemas/CreateTraceParams"
          type:
            - array
            - "null"
      type: object
    IngestSignalsV1ResponseBody:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
            - http://api.modelmetry.com//schemas/IngestSignalsV1ResponseBody.json
          format: uri
          readOnly: true
          type: string
      type: object
    Money:
      additionalProperties: false
      properties:
        Amount:
          type: number
        Currency:
          maxLength: 3
          minLength: 3
          type: string
      required:
        - Amount
        - Currency
      type: object
    Options:
      additionalProperties: false
      properties:
        APIKey:
          type: string
        APIVersion:
          type: string
        BaseURL:
          type: string
        DeploymentID:
          type: string
        FrequencyPenalty:
          format: double
          type: number
        FunctionCall:
          type: string
        Functions:
          items:
            type: string
          type:
            - array
            - "null"
        LogitBias:
          additionalProperties: {}
          type: object
        Logprobs:
          type: boolean
        MaxTokens:
          format: int64
          type: integer
        Model:
          type: string
        ModelList:
          items:
            type: string
          type:
            - array
            - "null"
        "N":
          format: int64
          type: integer
        PresencePenalty:
          format: double
          type: number
        Provider:
          type: string
        ResponseFormat:
          additionalProperties: {}
          type: object
        Seed:
          format: int64
          type: integer
        Stop:
          additionalProperties: {}
          type: object
        Stream:
          type: boolean
        Temperature:
          format: double
          maximum: 1
          minimum: 0
          type: number
        Timeout:
          format: double
          minimum: 0
          type: number
        ToolChoice:
          type: string
        Tools:
          items:
            $ref: "#/components/schemas/Tool"
          type:
            - array
            - "null"
        TopLogprobs:
          format: int64
          type: integer
        TopP:
          format: double
          maximum: 1
          minimum: 0
          type: number
        User:
          type: string
      type: object
    OtherFamilyData:
      additionalProperties: false
      type: object
    Output:
      additionalProperties: false
      properties:
        Messages:
          items:
            description: Represents a completion message.
            discriminator:
              mapping:
                assistant: "#/components/schemas/AssistantMessage"
                system: "#/components/schemas/SystemMessage"
                tool: "#/components/schemas/ToolMessage"
                user: "#/components/schemas/UserMessage"
              propertyName: Role
            oneOf:
              - $ref: "#/components/schemas/SystemMessage"
              - $ref: "#/components/schemas/UserMessage"
              - $ref: "#/components/schemas/AssistantMessage"
              - $ref: "#/components/schemas/ToolMessage"
            type: object
          type:
            - array
            - "null"
        Text:
          type: string
      type: object
    Payload:
      additionalProperties: false
      properties:
        Input:
          description: Input for completion
          oneOf:
            - $ref: "#/components/schemas/TextInput"
            - $ref: "#/components/schemas/ChatInput"
          type: object
        Options:
          $ref: "#/components/schemas/Options"
        Output:
          $ref: "#/components/schemas/Output"
      type: object
    RetrievalFamilyData:
      additionalProperties: false
      properties:
        Documents:
          items:
            $ref: "#/components/schemas/Document"
          type:
            - array
            - "null"
        Queries:
          items:
            $ref: "#/components/schemas/RetrievalQuery"
          type:
            - array
            - "null"
      required:
        - Queries
        - Documents
      type: object
    RetrievalQuery:
      additionalProperties: false
      properties:
        Embeddings:
          items:
            format: float
            type: number
          type:
            - array
            - "null"
        TextRepresentation:
          type: string
      required:
        - TextRepresentation
      type: object
    SimplifiedFinding:
      additionalProperties: false
      properties:
        At:
          format: date-time
          type: string
        Comment:
          type: string
        EvaluatorID:
          type:
            - string
            - "null"
        Metadata:
          additionalProperties: {}
          type: object
        Name:
          type: string
        Source:
          default: annotation
          enum:
            - annotation
            - evaluator
            - sdk
          type: string
        Value:
          oneOf:
            - type: number
            - type: boolean
            - type: string
            - properties:
                Unit:
                  type: string
                Value:
                  type: number
              required:
                - Value
                - Unit
              type: object
      required:
        - Name
        - Value
        - Source
        - Comment
        - Metadata
        - EvaluatorID
        - At
      type: object
    Span:
      additionalProperties: false
      properties:
        Completion:
          $ref: "#/components/schemas/CompletionFamilyData"
        CreatedAt:
          format: date-time
          type: string
        Embeddings:
          $ref: "#/components/schemas/EmbeddingsFamilyData"
        End:
          format: date-time
          type: string
        Events:
          items:
            $ref: "#/components/schemas/Event"
          type:
            - array
            - "null"
        Family:
          type: string
        Findings:
          items:
            $ref: "#/components/schemas/Finding"
          type:
            - array
            - "null"
        ID:
          type: string
        Message:
          type: string
        Metadata:
          additionalProperties: {}
          type: object
        Name:
          type: string
        Other:
          $ref: "#/components/schemas/OtherFamilyData"
        ParentID:
          type:
            - string
            - "null"
        Retrieval:
          $ref: "#/components/schemas/RetrievalFamilyData"
        Severity:
          type: string
        Start:
          format: date-time
          type: string
        TenantID:
          type: string
        TraceID:
          type: string
        UpdatedAt:
          format: date-time
          type: string
        XID:
          type: string
      required:
        - ID
        - XID
        - TenantID
        - TraceID
        - ParentID
        - Name
        - Family
        - Severity
        - Message
        - Start
        - End
        - Metadata
        - Events
        - Findings
        - UpdatedAt
        - CreatedAt
      type: object
    SummarisedEntry:
      additionalProperties: false
      properties:
        CheckID:
          type:
            - string
            - "null"
        DurationMs:
          format: int64
          type: integer
        EvaluatorID:
          type: string
        Findings:
          items:
            $ref: "#/components/schemas/SimplifiedFinding"
          type:
            - array
            - "null"
        ID:
          type: string
        InstanceID:
          type:
            - string
            - "null"
        Message:
          type: string
        Outcome:
          type: string
        Score:
          format: double
          type:
            - number
            - "null"
        Skip:
          type: string
        SpanID:
          type:
            - string
            - "null"
        TenantID:
          type: string
        TraceID:
          type:
            - string
            - "null"
      required:
        - ID
        - TenantID
        - CheckID
        - InstanceID
        - TraceID
        - SpanID
        - EvaluatorID
        - Outcome
        - Skip
        - Message
        - Score
        - Findings
        - DurationMs
      type: object
    SystemMessage:
      additionalProperties: false
      properties:
        Contents:
          items:
            description: Represents a part of a completion message.
            oneOf:
              - $ref: "#/components/schemas/TextPart"
              - $ref: "#/components/schemas/DataPart"
            type: object
          type:
            - array
            - "null"
        Name:
          type: string
        Role:
          enum:
            - system
          type: string
      required:
        - Role
        - Contents
      type: object
    TextInput:
      additionalProperties: false
      properties:
        Text:
          type: string
      required:
        - Text
      type: object
    TextPart:
      additionalProperties: false
      properties:
        Text:
          type: string
      required:
        - Text
      type: object
    Tool:
      additionalProperties: false
      properties:
        Description:
          type: string
        Name:
          type: string
        Parameters: {}
      required:
        - Name
        - Description
        - Parameters
      type: object
    ToolCall:
      additionalProperties: false
      properties:
        Function:
          $ref: "#/components/schemas/Function"
        ID:
          type: string
        Type:
          enum:
            - function
          type: string
      required:
        - Type
        - ID
        - Function
      type: object
    ToolMessage:
      additionalProperties: false
      properties:
        Contents:
          items:
            description: Represents a part of a completion message.
            oneOf:
              - $ref: "#/components/schemas/TextPart"
              - $ref: "#/components/schemas/DataPart"
            type: object
          type:
            - array
            - "null"
        Role:
          enum:
            - tool
          type: string
        ToolCallID:
          type: string
      required:
        - Contents
        - Role
        - ToolCallID
      type: object
    Trace:
      additionalProperties: false
      properties:
        CreatedAt:
          format: date-time
          type: string
        End:
          format: date-time
          type: string
        ID:
          type: string
        Metadata:
          additionalProperties: {}
          type: object
        Name:
          type: string
        SessionID:
          type:
            - string
            - "null"
        Start:
          format: date-time
          type: string
        TenantID:
          type: string
        UpdatedAt:
          format: date-time
          type: string
        XID:
          type: string
      required:
        - ID
        - XID
        - TenantID
        - Name
        - Start
        - End
        - Metadata
        - UpdatedAt
        - CreatedAt
      type: object
    Usage:
      additionalProperties: false
      properties:
        Input:
          $ref: "#/components/schemas/UsageValue"
        Output:
          $ref: "#/components/schemas/UsageValue"
        Total:
          $ref: "#/components/schemas/UsageValue"
      type: object
    UsageValue:
      additionalProperties: false
      properties:
        Amount:
          format: double
          type: number
        Unit:
          default: tokens
          type: string
      required:
        - Amount
        - Unit
      type: object
    UserMessage:
      additionalProperties: false
      properties:
        Contents:
          items:
            description: Represents a part of a completion message.
            oneOf:
              - $ref: "#/components/schemas/TextPart"
              - $ref: "#/components/schemas/DataPart"
            type: object
          type:
            - array
            - "null"
        Name:
          type: string
        Role:
          enum:
            - user
          type: string
      required:
        - Contents
        - Role
      type: object
  securitySchemes:
    apikeyAuth:
      in: header
      name: X-API-KEY
      type: apiKey
info:
  title: Modelmetry API
  version: 1.0.0
openapi: 3.1.0
paths:
  /checks:
    post:
      operationId: check-payload
      parameters:
        - explode: false
          in: query
          name: dryrun
          schema:
            type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CheckPayloadRequestBody"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GuardrailCheck"
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ErrorModel"
          description: Error
      security:
        - apikeyAuth: []
      summary: Check payload
  /signals/ingest/v1:
    post:
      operationId: ingest-signals-v1
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IngestSignalsV1RequestBody"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IngestSignalsV1ResponseBody"
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ErrorModel"
          description: Error
      security:
        - apikeyAuth: []
      summary: Ingest signals v1
servers:
  - url: http://api.modelmetry.com/