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

# Create score

> Create a score record for a span or trace. Scores are used to track quality metrics,
evaluation results, and human feedback.

<Note>This endpoint was consolidated from `/v1/score` (singular). The legacy path still works but `/v1/scores` is preferred.</Note>



## OpenAPI

````yaml /openapi.yaml post /v1/scores
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: 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: Retrieve the effective synced project configuration.
    name: Config
  - description: List and retrieve datasets.
    name: Datasets
  - 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: >-
      Trigger and inspect managed deployments. POST returns 202; deployments run
      asynchronously and progress is observed via GET.
    name: Deployments
  - description: >-
      Per-app named environments (e.g. `dev`, `prod`). CRUD for env lifecycle;
      promote/rollback routes land alongside in this group as feature 054 lands
      the saga.
    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: Service health checks.
    name: Health
paths:
  /v1/scores:
    post:
      tags:
        - Scoring
      summary: Create score
      description: >-
        Create a score record for a span or trace. Scores are used to track
        quality metrics,

        evaluation results, and human feedback.


        <Note>This endpoint was consolidated from `/v1/score` (singular). The
        legacy path still works but `/v1/scores` is preferred.</Note>
      operationId: create-score
      requestBody:
        content:
          application/json:
            schema:
              properties:
                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
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  id:
                    format: uuid
                    type: string
                  message:
                    type: string
                required:
                  - message
                  - id
                type: object
          description: Score created.
        '400':
          content:
            application/json:
              schema:
                properties:
                  error:
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    type: object
                required:
                  - error
                type: object
          description: Invalid request body.
        '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.
        '500':
          content:
            application/json:
              schema:
                properties:
                  error:
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    type: object
                required:
                  - error
                type: object
          description: Internal server error.
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

````