> ## Documentation Index
> Fetch the complete documentation index at: https://puzzlet-9ba7bb98.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create scores (batch)

> Create up to 1000 scores in a single request. Each item is validated independently and the response always contains a per-item results array.

Status codes:
  - `201 Created` — every item succeeded.
  - `207 Multi-Status` — at least one item failed validation (e.g. missing `resource_id` or invalid `dataType`).
  - `400 Bad Request` — every item failed validation (or the envelope itself is malformed).
  - `413 Payload Too Large` — the request contains more than 1000 items.
  - `500 Internal Server Error` — the batch insert against analytics storage failed; no items were persisted.

Pass an optional `client_id` on each item (max 128 chars) to correlate the server-generated `id` back to your own identifier in the results array. The server never inspects or stores `client_id`.



## OpenAPI

````yaml /openapi.yaml post /v1/scores/batch
openapi: 3.0.3
info:
  contact:
    email: hello@agentmark.co
    url: https://docs.agentmark.co
  description: >-
    The AgentMark Gateway API lets you ingest traces, create scores, and
    retrieve prompt templates programmatically.


    Most developers should use the [AgentMark SDK](/introduction/overview) for
    integration.

    The REST API is for cases where you need direct HTTP access or are building
    a custom integration.


    Versioning: every endpoint is prefixed with `/v1/`. Breaking changes ship
    under a new version prefix (`/v2/`, etc.) with a 90-day-minimum deprecation
    window — see [API versioning & stability](/api-reference/versioning) for the
    full policy on what constitutes a breaking vs. additive change.
  title: AgentMark Gateway API
  version: '1.0'
servers:
  - description: Production (AgentMark Cloud)
    url: https://api.agentmark.co
  - description: Local dev server (`npx @agentmark-ai/cli dev`)
    url: http://localhost:9418
security:
  - AppId: []
    BearerAuth: []
tags:
  - description: Ingest, query, and export OpenTelemetry trace data.
    name: Traces
  - description: >-
      Coding-agent session ingest (outerlayer sync) and content-addressed
      session images.
    name: Agents
  - description: >-
      Eval trial-result ingest: per-trial score rows plus full-fidelity artifact
      blobs.
    name: Evals
  - description: Query individual spans across traces.
    name: Spans
  - description: Create, retrieve, list, and delete score records for spans and traces.
    name: Scoring
  - description: Structured-filter search across observability resources.
    name: Search
  - description: Query server feature availability.
    name: Capabilities
  - description: Per-model LLM pricing data. Public, unauthenticated.
    name: Pricing
  - description: >-
      Create, list, and revoke tenant API keys. Plaintext returned exactly once
      at creation.
    name: API Keys
  - description: >-
      List and retrieve score configuration definitions from the synced project
      config.
    name: Score Configs
  - description: Per-app named environments (e.g. `dev`, `prod`). CRUD for env lifecycle.
    name: Environments
  - description: >-
      App CRUD — the top-level tenant entity every other resource hangs off.
      Lets a headless agent provision an app without the dashboard.
    name: Apps
  - description: >-
      Cloud workers — terminal coding agents on managed compute. Launch one-shot
      runs or persistent multi-turn sessions against the app's connected repo;
      every response carries the dashboard deep link to the live thread.
    name: Workers
  - description: Service health checks.
    name: Health
paths:
  /v1/scores/batch:
    post:
      tags:
        - Scoring
      summary: Create scores (batch)
      description: >-
        Create up to 1000 scores in a single request. Each item is validated
        independently and the response always contains a per-item results array.


        Status codes:
          - `201 Created` — every item succeeded.
          - `207 Multi-Status` — at least one item failed validation (e.g. missing `resource_id` or invalid `dataType`).
          - `400 Bad Request` — every item failed validation (or the envelope itself is malformed).
          - `413 Payload Too Large` — the request contains more than 1000 items.
          - `500 Internal Server Error` — the batch insert against analytics storage failed; no items were persisted.

        Pass an optional `client_id` on each item (max 128 chars) to correlate
        the server-generated `id` back to your own identifier in the results
        array. The server never inspects or stores `client_id`.
      operationId: create-scores-batch
      requestBody:
        content:
          application/json:
            schema:
              properties:
                scores:
                  items:
                    properties:
                      client_id:
                        maxLength: 128
                        type: string
                      label:
                        type: string
                      name:
                        minLength: 1
                        type: string
                      reason:
                        type: string
                      resource_id:
                        minLength: 1
                        type: string
                      score:
                        type: number
                      source:
                        default: api
                        enum:
                          - experiment
                          - annotation
                          - api
                        type: string
                    required:
                      - resource_id
                      - name
                      - score
                    type: object
                  maxItems: 1000
                  minItems: 1
                  type: array
              required:
                - scores
              type: object
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  data:
                    properties:
                      results:
                        items:
                          oneOf:
                            - properties:
                                client_id:
                                  type: string
                                id:
                                  format: uuid
                                  type: string
                                status:
                                  enum:
                                    - success
                                  type: string
                              required:
                                - status
                                - id
                              type: object
                            - properties:
                                client_id:
                                  type: string
                                error:
                                  properties:
                                    code:
                                      type: string
                                    message:
                                      type: string
                                  required:
                                    - code
                                    - message
                                  type: object
                                status:
                                  enum:
                                    - error
                                  type: string
                              required:
                                - status
                                - error
                              type: object
                        type: array
                      summary:
                        properties:
                          failed:
                            minimum: 0
                            type: integer
                          succeeded:
                            minimum: 0
                            type: integer
                          total:
                            minimum: 0
                            type: integer
                        required:
                          - total
                          - succeeded
                          - failed
                        type: object
                    required:
                      - results
                      - summary
                    type: object
                required:
                  - data
                type: object
          description: All scores created successfully.
        '207':
          content:
            application/json:
              schema:
                properties:
                  data:
                    properties:
                      results:
                        items:
                          oneOf:
                            - properties:
                                client_id:
                                  type: string
                                id:
                                  format: uuid
                                  type: string
                                status:
                                  enum:
                                    - success
                                  type: string
                              required:
                                - status
                                - id
                              type: object
                            - properties:
                                client_id:
                                  type: string
                                error:
                                  properties:
                                    code:
                                      type: string
                                    message:
                                      type: string
                                  required:
                                    - code
                                    - message
                                  type: object
                                status:
                                  enum:
                                    - error
                                  type: string
                              required:
                                - status
                                - error
                              type: object
                        type: array
                      summary:
                        properties:
                          failed:
                            minimum: 0
                            type: integer
                          succeeded:
                            minimum: 0
                            type: integer
                          total:
                            minimum: 0
                            type: integer
                        required:
                          - total
                          - succeeded
                          - failed
                        type: object
                    required:
                      - results
                      - summary
                    type: object
                required:
                  - data
                type: object
          description: Partial success — some items succeeded and some failed validation.
        '400':
          content:
            application/json:
              schema:
                properties:
                  error:
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    type: object
                required:
                  - error
                type: object
          description: Malformed request body, or every item failed validation.
        '401':
          content:
            application/json:
              schema:
                properties:
                  error:
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    type: object
                required:
                  - error
                type: object
          description: Missing or invalid API key.
        '413':
          content:
            application/json:
              schema:
                properties:
                  error:
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    type: object
                required:
                  - error
                type: object
          description: Batch exceeds max size of 1000.
        '500':
          content:
            application/json:
              schema:
                properties:
                  error:
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    type: object
                required:
                  - error
                type: object
          description: Analytics-layer insert failed; no items were persisted.
components:
  securitySchemes:
    AppId:
      description: >-
        Application ID for tenant scoping. X-Outerlayer-App-Id is accepted as an
        equivalent header.
      in: header
      name: X-Agentmark-App-Id
      type: apiKey
    BearerAuth:
      description: API key (sk_agentmark_*)
      scheme: bearer
      type: http

````