> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ambral.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To set Ambral up in a project, run `npx ambral@latest skill install` in the project's root. It installs Ambral's skill, matched to the CLI's version, and the skill says how to do everything these pages describe with the `ambral` CLI. Prefer it to working from these pages. Never ask anyone for an Ambral API key, and never handle one: the person creates it in the web app and stores it where their app reads its secrets.

# Report scenarios to an offline run

> 1 to 100 reports, each one run of a scenario as the harness scored it, stored in one transaction. Answers one result per report, in the order sent: stored, with its trace and its repeat, the run of its scenario it is, from 0; or refused, with a `code`, a sentence, and the bound it broke, if one did, the others stored as if it weren't sent: a report past a bound on one (its task's bytes as JSON, a reason's length, its judge calls) is refused with that bound as `limit`. A task sent as its id alone takes the content an earlier report in the request sent for its scenario, or else the revision of it the run last stored, so a scenario's content need be sent once a run; a run that stored none stores the id alone as the scenario's content. A session already reported answers what was stored for it, so a request sent again stores nothing twice. A run that isn't open takes none (`OfflineRunNotOpen`), a body past its bound in bytes is `OfflineRequestTooLarge`, and past the org's budget, `TooManyAttempts`: either way nothing is stored, and the same request can be sent again, after `retryAfter` seconds for the latter.



## OpenAPI

````yaml /api-reference/report.json post /api/report/v1/runs/{run}/reports
openapi: 3.1.0
info:
  title: Ambral Report API
  version: '1'
servers:
  - url: https://app.ambral.ai
security: []
tags:
  - name: Runs
    description: >-
      Offline runs: a suite's scenarios, run and scored by its own harness,
      reported as they finish
paths:
  /api/report/v1/runs/{run}/reports:
    post:
      tags:
        - Runs
      summary: Report scenarios to an offline run
      description: >-
        1 to 100 reports, each one run of a scenario as the harness scored it,
        stored in one transaction. Answers one result per report, in the order
        sent: stored, with its trace and its repeat, the run of its scenario it
        is, from 0; or refused, with a `code`, a sentence, and the bound it
        broke, if one did, the others stored as if it weren't sent: a report
        past a bound on one (its task's bytes as JSON, a reason's length, its
        judge calls) is refused with that bound as `limit`. A task sent as its
        id alone takes the content an earlier report in the request sent for its
        scenario, or else the revision of it the run last stored, so a
        scenario's content need be sent once a run; a run that stored none
        stores the id alone as the scenario's content. A session already
        reported answers what was stored for it, so a request sent again stores
        nothing twice. A run that isn't open takes none (`OfflineRunNotOpen`), a
        body past its bound in bytes is `OfflineRequestTooLarge`, and past the
        org's budget, `TooManyAttempts`: either way nothing is stored, and the
        same request can be sent again, after `retryAfter` seconds for the
        latter.
      operationId: runs.report
      parameters:
        - name: run
          in: path
          schema:
            $ref: '#/components/schemas/RunId'
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfflineReports'
        required: true
      responses:
        '200':
          description: >-
            One result per report, in the order sent: stored, or refused with
            why.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfflineReported'
        '401':
          description: >-
            No API key, or one that is unknown or revoked, or whose org isn't
            active.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedEncoded'
        '404':
          description: No score run with this id exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunNotFoundEncoded'
        '409':
          description: >-
            The run takes no reports: it isn't an offline run, or it isn't open.
            The request stored nothing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfflineRunNotOpenEncoded'
        '413':
          description: >-
            The request's body is larger than the report API takes, `limit`
            bytes: nothing in it was stored.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfflineRequestTooLargeEncoded'
        '429':
          description: >-
            Too many requests. Send the request again after `retryAfter`
            seconds, which the `Retry-After` header also gives.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyAttemptsEncoded'
        '503':
          description: Something the request needs couldn't be reached. Retry the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableEncoded'
      security:
        - bearer: []
components:
  schemas:
    RunId:
      type: string
      pattern: >-
        ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
      format: uuid
    OfflineReports:
      type: object
      properties:
        reports:
          type: array
          items:
            $ref: '#/components/schemas/OfflineReport'
          minItems: 1
          maxItems: 100
      required:
        - reports
      additionalProperties: false
    OfflineReported:
      type: object
      properties:
        results:
          type: array
          items:
            anyOf:
              - $ref: '#/components/schemas/OfflineReportStored'
              - $ref: '#/components/schemas/OfflineReportRefused'
      required:
        - results
      additionalProperties: false
      description: 'One result per report, in the order sent: stored, or refused with why.'
    UnauthorizedEncoded:
      type: object
      properties:
        _tag:
          type: string
          enum:
            - Unauthorized
      required:
        - _tag
      additionalProperties: false
    RunNotFoundEncoded:
      type: object
      properties:
        _tag:
          type: string
          enum:
            - RunNotFound
        run:
          $ref: '#/components/schemas/RunId'
      required:
        - _tag
        - run
      additionalProperties: false
    OfflineRunNotOpenEncoded:
      type: object
      properties:
        _tag:
          type: string
          enum:
            - OfflineRunNotOpen
        run:
          $ref: '#/components/schemas/RunId'
      required:
        - _tag
        - run
      additionalProperties: false
    OfflineRequestTooLargeEncoded:
      type: object
      properties:
        _tag:
          type: string
          enum:
            - OfflineRequestTooLarge
        limit:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
      required:
        - _tag
        - limit
      additionalProperties: false
    TooManyAttemptsEncoded:
      type: object
      properties:
        _tag:
          type: string
          enum:
            - TooManyAttempts
        message:
          type: string
        retryAfter:
          $ref: '#/components/schemas/Seconds'
      required:
        - _tag
        - message
        - retryAfter
      additionalProperties: false
    ServiceUnavailableEncoded:
      type: object
      properties:
        _tag:
          type: string
          enum:
            - ServiceUnavailable
      required:
        - _tag
      additionalProperties: false
    OfflineReport:
      type: object
      properties:
        session:
          allOf:
            - $ref: '#/components/schemas/SessionId'
            - description: >-
                The session its model calls carried, `x-session-id`: one per run
                of a scenario
        task:
          $ref: '#/components/schemas/OfflineTask'
        passed:
          anyOf:
            - type: boolean
            - type: 'null'
          allOf:
            - description: >-
                The harness's own verdict on the scenario. Absent, the run reads
                its scores alone.
        rewards:
          $ref: '#/components/schemas/OfflineRewards'
        metrics:
          anyOf:
            - $ref: '#/components/schemas/Metrics'
            - type: 'null'
        reasons:
          anyOf:
            - type: object
              propertyNames:
                type: string
                minLength: 1
              additionalProperties:
                $ref: '#/components/schemas/JudgeReason'
            - type: 'null'
          allOf:
            - description: Why each score was given, by the name of its reward or metric
        judgeCalls:
          anyOf:
            - type: array
              items:
                $ref: '#/components/schemas/JudgeCall'
            - type: 'null'
          allOf:
            - description: Each judge exchange behind the scores, as verifiers records it
        errors:
          anyOf:
            - type: array
              items:
                $ref: '#/components/schemas/VerifiersError'
            - type: 'null'
          allOf:
            - description: >-
                What failed while the scenario ran, as verifiers records an
                error
      required:
        - session
        - task
        - rewards
      additionalProperties: false
    OfflineReportStored:
      type: object
      properties:
        session:
          $ref: '#/components/schemas/SessionId'
        trace:
          $ref: '#/components/schemas/TracePublicId'
        repeat:
          $ref: '#/components/schemas/RepeatIndex'
      required:
        - session
        - trace
        - repeat
      additionalProperties: false
    OfflineReportRefused:
      type: object
      properties:
        session:
          $ref: '#/components/schemas/SessionId'
        code:
          $ref: '#/components/schemas/OfflineRefusalCode'
        message:
          type: string
        limit:
          anyOf:
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
      required:
        - session
        - code
        - message
      additionalProperties: false
    Seconds:
      type: integer
      minimum: 0
      maximum: 9007199254740991
      description: A duration, in whole seconds
    SessionId:
      type: string
    OfflineTask:
      type: object
      properties:
        idx:
          anyOf:
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        id:
          $ref: '#/components/schemas/ScenarioId'
        name:
          anyOf:
            - type: string
            - type: 'null'
        description:
          anyOf:
            - type: string
            - type: 'null'
        prompt:
          anyOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/Message'
            - type: 'null'
        system_prompt:
          anyOf:
            - type: string
            - type: 'null'
        image:
          anyOf:
            - type: string
            - type: 'null'
        workdir:
          anyOf:
            - type: string
            - type: 'null'
        agent_user:
          anyOf:
            - type: string
            - type: 'null'
        skills:
          type: array
          items:
            $ref: '#/components/schemas/SkillSource'
        network_allow:
          type: array
          items:
            type: string
        network_block:
          type: array
          items:
            type: string
        artifacts:
          type: array
          items:
            $ref: '#/components/schemas/Artifact'
        artifact_max_bytes:
          type: integer
          maximum: 9007199254740991
          exclusiveMinimum: 0
        timeout:
          $ref: '#/components/schemas/TaskTimeout'
        resources:
          $ref: '#/components/schemas/TaskResources'
      required:
        - id
      allOf:
        - type: object
          additionalProperties: {}
    OfflineRewards:
      type: object
      propertyNames:
        type: string
        minLength: 1
      additionalProperties:
        anyOf:
          - $ref: '#/components/schemas/OfflineReward'
          - type: 'null'
      description: >-
        Each reward by its name: a score from 0 (fails) to 1 (passes), and a
        weight from 0 to 1000, 1 when absent; `null` for one that didn't run. A
        suite that scores on another scale divides by it; what else it measures
        is a metric, which has no bound. The scenario's score is their weighted
        mean.
    Metrics:
      type: object
      propertyNames:
        type: string
        minLength: 1
      additionalProperties:
        anyOf:
          - type: number
          - type: 'null'
    JudgeReason:
      type: string
    JudgeCall:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/ScorerName'
        request:
          $ref: '#/components/schemas/JudgeRequest'
        response:
          $ref: '#/components/schemas/JudgeResponse'
      required:
        - name
        - request
        - response
      additionalProperties: false
    VerifiersError:
      type: object
      properties:
        type:
          type: string
        message:
          type: string
        status_code:
          anyOf:
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        traceback:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - type
        - message
      additionalProperties: false
    TracePublicId:
      type: string
    RepeatIndex:
      type: integer
      minimum: 0
      maximum: 9007199254740991
    OfflineRefusalCode:
      type: string
      minLength: 1
    ScenarioId:
      type: string
      minLength: 1
      maxLength: 512
    Message:
      anyOf:
        - $ref: '#/components/schemas/SystemMessage'
        - $ref: '#/components/schemas/UserMessage'
        - $ref: '#/components/schemas/AssistantMessage'
        - $ref: '#/components/schemas/ToolMessage'
    SkillSource:
      anyOf:
        - type: string
        - type: object
          properties:
            runtime:
              type: string
          required:
            - runtime
          additionalProperties: false
    Artifact:
      type: object
      properties:
        source:
          type: string
        exclude:
          type: array
          items:
            type: string
        required:
          type: boolean
      required:
        - source
      additionalProperties: false
    TaskTimeout:
      type: object
      properties:
        setup:
          anyOf:
            - type: number
            - type: 'null'
        agent:
          anyOf:
            - type: number
            - type: 'null'
        finalize:
          anyOf:
            - type: number
            - type: 'null'
        scoring:
          anyOf:
            - type: number
            - type: 'null'
      additionalProperties: false
    TaskResources:
      type: object
      properties:
        cpu:
          anyOf:
            - type: number
            - type: 'null'
        memory:
          anyOf:
            - type: number
            - type: 'null'
        gpu:
          anyOf:
            - type: string
            - type: 'null'
        disk:
          anyOf:
            - type: number
            - type: 'null'
      additionalProperties: false
    OfflineReward:
      type: object
      properties:
        score:
          $ref: '#/components/schemas/Score'
        weight:
          type: number
          minimum: 0
          maximum: 1000
      required:
        - score
      additionalProperties: false
    ScorerName:
      type: string
      minLength: 1
    JudgeRequest:
      type: object
      description: >-
        What the judge asked, as it recorded it. Ambral's judges record `model`,
        the judge's catalog model, and `messages`, the messages it sent, each
        image it was sent recorded in place by digest, not as the image: its URL
        is `omitted:` followed by the digest of the image's URL in the trace.
    JudgeResponse:
      type: object
      properties:
        message:
          $ref: '#/components/schemas/AssistantMessage'
        parsed:
          anyOf:
            - {}
            - type: 'null'
        usage:
          anyOf:
            - $ref: '#/components/schemas/Usage'
            - type: 'null'
      required:
        - message
        - parsed
        - usage
      additionalProperties: false
    SystemMessage:
      type: object
      properties:
        role:
          type: string
          enum:
            - system
        content:
          $ref: '#/components/schemas/MessageContent'
      required:
        - role
        - content
      additionalProperties: false
    UserMessage:
      type: object
      properties:
        role:
          type: string
          enum:
            - user
        content:
          $ref: '#/components/schemas/MessageContent'
      required:
        - role
        - content
      additionalProperties: false
    AssistantMessage:
      type: object
      properties:
        role:
          type: string
          enum:
            - assistant
        content:
          anyOf:
            - type: string
            - type: 'null'
        reasoning_content:
          anyOf:
            - type: string
            - type: 'null'
        tool_calls:
          anyOf:
            - type: array
              items:
                $ref: '#/components/schemas/ToolCall'
            - type: 'null'
        provider_state:
          anyOf:
            - type: array
              items:
                type: object
            - type: 'null'
      required:
        - role
      additionalProperties: false
    ToolMessage:
      type: object
      properties:
        role:
          type: string
          enum:
            - tool
        tool_call_id:
          type: string
        content:
          $ref: '#/components/schemas/MessageContent'
        name:
          anyOf:
            - $ref: '#/components/schemas/ToolName'
            - type: 'null'
      required:
        - role
        - tool_call_id
        - content
      additionalProperties: false
    Score:
      type: number
      minimum: 0
      maximum: 1
    Usage:
      type: object
      properties:
        prompt_tokens:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: >-
            Input tokens not read from the prompt cache. Unlike Chat
            Completions' `prompt_tokens`, it leaves out `cached_input_tokens`:
            the call's whole input is the two added.
        completion_tokens:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: Output tokens, `reasoning_tokens` included.
        cached_input_tokens:
          anyOf:
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
          description: >-
            Input tokens read from the prompt cache, which `prompt_tokens`
            leaves out.
        reasoning_tokens:
          anyOf:
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
          description: The part of `completion_tokens` the model spent reasoning.
        cost:
          anyOf:
            - type: number
            - type: 'null'
      required:
        - prompt_tokens
        - completion_tokens
      additionalProperties: false
    MessageContent:
      anyOf:
        - type: string
        - type: array
          items:
            $ref: '#/components/schemas/ContentPart'
    ToolCall:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - function
            - custom
        name:
          $ref: '#/components/schemas/ToolName'
        namespace:
          anyOf:
            - type: string
            - type: 'null'
        arguments:
          type: string
      required:
        - id
        - name
        - arguments
      additionalProperties: false
    ToolName:
      type: string
    ContentPart:
      anyOf:
        - $ref: '#/components/schemas/TextContentPart'
        - $ref: '#/components/schemas/ImageUrlContentPart'
    TextContentPart:
      type: object
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string
      required:
        - type
        - text
      additionalProperties: false
    ImageUrlContentPart:
      type: object
      properties:
        type:
          type: string
          enum:
            - image_url
        image_url:
          $ref: '#/components/schemas/ImageUrlSource'
      required:
        - type
        - image_url
      additionalProperties: false
    ImageUrlSource:
      type: object
      properties:
        url:
          type: string
      required:
        - url
      additionalProperties: false
  securitySchemes:
    bearer:
      description: 'The org''s API key: the one its agent calls the Gateway with.'
      type: http
      scheme: Bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.