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

# Record a deneme

> One scored paper. A TYT and an AYT sat under the same exam name are two requests —
their nets are never summed.

Each subject result needs either the counts (`dogru` + `yanlis`, `bos` optional) or a
bare `net` when the counts are unknown. When the counts are present the net is
computed — TYT/AYT: doğru − yanlış/4, LGS: doğru − yanlış/3 — and a claimed net is
ignored. Per-topic rows are optional detail; they feed the topic performance tables.

Subjects accept display names, aliases, short codes, or canonical keys. An unknown
subject is a 400, never a silent new subject.



## OpenAPI

````yaml /api-reference/openapi.json post /api/denemeler
openapi: 3.1.0
info:
  title: Lala Client API
  description: >-
    The HTTP API behind Lala, the AI study companion for Turkish YKS and LGS
    students. This document is generated from the Zod schemas that validate each
    request at runtime. Do not hand-edit openapi.json. Student-visible text is
    Turkish. All identifiers are English.
  version: 1.0.0
servers:
  - url: https://client-api.lala.ist
    description: production
  - url: http://localhost:3000
    description: local dev
security:
  - supabaseJwt: []
tags:
  - name: chat
    description: The chat stream, the message history, and reactions
  - name: media
    description: Upload and read message attachments
  - name: plan
    description: The study planner — blocks of work on a day
  - name: journey
    description: Deneme results, topic performance, study-hours stats, and the streak
  - name: profile
    description: The student profile and onboarding
  - name: devices
    description: Push notification devices
  - name: system
    description: Health check
paths:
  /api/denemeler:
    post:
      tags:
        - journey
      summary: Record a deneme
      description: >-
        One scored paper. A TYT and an AYT sat under the same exam name are two
        requests —

        their nets are never summed.


        Each subject result needs either the counts (`dogru` + `yanlis`, `bos`
        optional) or a

        bare `net` when the counts are unknown. When the counts are present the
        net is

        computed — TYT/AYT: doğru − yanlış/4, LGS: doğru − yanlış/3 — and a
        claimed net is

        ignored. Per-topic rows are optional detail; they feed the topic
        performance tables.


        Subjects accept display names, aliases, short codes, or canonical keys.
        An unknown

        subject is a 400, never a silent new subject.
      operationId: postApiDenemeler
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DenemeInput'
      responses:
        '201':
          description: The recorded deneme
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deneme'
        '400':
          description: The input is not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The token is missing, expired, or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    DenemeInput:
      type: object
      properties:
        examType:
          $ref: '#/components/schemas/ExamType'
        field:
          description: AYT only — ignored on TYT and LGS papers.
          anyOf:
            - type: string
              enum:
                - EA
                - Sayısal
                - Sözel
            - type: 'null'
        name:
          anyOf:
            - type: string
              maxLength: 160
            - type: 'null'
        publisher:
          anyOf:
            - type: string
              maxLength: 120
            - type: 'null'
        takenDate:
          type: string
          description: Local Istanbul calendar date, `YYYY-MM-DD`.
        durationMin:
          anyOf:
            - type: integer
              minimum: 1
              maximum: 600
            - type: 'null'
        notes:
          anyOf:
            - type: string
              maxLength: 1000
            - type: 'null'
        subjects:
          minItems: 1
          maxItems: 25
          type: array
          items:
            $ref: '#/components/schemas/DenemeSubjectInput'
        topics:
          maxItems: 120
          type: array
          items:
            $ref: '#/components/schemas/DenemeTopicInput'
      required:
        - examType
        - takenDate
        - subjects
    Deneme:
      type: object
      properties:
        id:
          type: string
          format: uuid
          pattern: >-
            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        examType:
          $ref: '#/components/schemas/ExamType'
        field:
          anyOf:
            - type: string
              enum:
                - EA
                - Sayısal
                - Sözel
            - type: 'null'
          description: AYT only. Null on TYT and LGS papers.
        name:
          anyOf:
            - type: string
            - type: 'null'
          description: '`Bilgi Sarmal Türkiye Geneli`, …'
        publisher:
          anyOf:
            - type: string
            - type: 'null'
        takenDate:
          type: string
          description: Local Istanbul calendar date, `YYYY-MM-DD`.
        durationMin:
          anyOf:
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        totalNet:
          type: number
          description: Sum of the subject nets. Recomputed on every write.
        source:
          type: string
          enum:
            - manual
            - chat
          description: '`chat` when Lala logged it from the conversation.'
        createdBy:
          type: string
          enum:
            - student
            - lala
        notes:
          anyOf:
            - type: string
            - type: 'null'
        subjects:
          type: array
          items:
            $ref: '#/components/schemas/DenemeSubjectResult'
          description: Booklet order.
        topics:
          type: array
          items:
            $ref: '#/components/schemas/DenemeTopicResult'
        createdAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        updatedAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
      required:
        - id
        - examType
        - field
        - name
        - publisher
        - takenDate
        - durationMin
        - totalNet
        - source
        - createdBy
        - notes
        - subjects
        - topics
        - createdAt
        - updatedAt
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        issues:
          description: >-
            Present only on a 400 raised by request validation, capped at 10
            entries. Every other error carries `error` alone.
          type: array
          items:
            $ref: '#/components/schemas/ValidationIssue'
      required:
        - error
      description: Error body. `error` is a short English string.
    ExamType:
      type: string
      enum:
        - TYT
        - AYT
        - LGS
      description: One scored paper. TYT and AYT nets are never summed.
    DenemeSubjectInput:
      type: object
      properties:
        subject:
          type: string
          minLength: 1
          maxLength: 64
          description: >-
            A subject name, alias, short code, or canonical key: `Matematik`,
            `mat` and `tyt_matematik` all land on `tyt_matematik`. Unknown
            subjects are a 400.
        dogru:
          anyOf:
            - type: integer
              minimum: 0
              maximum: 200
            - type: 'null'
        yanlis:
          anyOf:
            - type: integer
              minimum: 0
              maximum: 200
            - type: 'null'
        bos:
          anyOf:
            - type: integer
              minimum: 0
              maximum: 200
            - type: 'null'
        net:
          description: >-
            Only read when doğru/yanlış are unknown — a known count pair always
            wins and the net is computed from it.
          anyOf:
            - type: number
              minimum: -50
              maximum: 200
            - type: 'null'
      required:
        - subject
    DenemeTopicInput:
      type: object
      properties:
        subject:
          type: string
          minLength: 1
          maxLength: 64
          description: >-
            A subject name, alias, short code, or canonical key: `Matematik`,
            `mat` and `tyt_matematik` all land on `tyt_matematik`. Unknown
            subjects are a 400.
        topic:
          type: string
          minLength: 1
          maxLength: 80
        dogru:
          type: integer
          minimum: 0
          maximum: 200
        yanlis:
          type: integer
          minimum: 0
          maximum: 200
        bos:
          type: integer
          minimum: 0
          maximum: 200
      required:
        - subject
        - topic
        - dogru
        - yanlis
        - bos
    DenemeSubjectResult:
      type: object
      properties:
        subject:
          type: string
          description: >-
            Canonical subject key — exam-prefixed, e.g. `tyt_matematik`,
            `ayt_tarih1`, `lgs_fen`.
        label:
          type: string
          description: Turkish display name. Read-only.
        short:
          type: string
          description: 'Short code for dense views: `TÜR`, `MAT`. Read-only.'
        dogru:
          anyOf:
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        yanlis:
          anyOf:
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        bos:
          anyOf:
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        net:
          type: number
          description: >-
            TYT/AYT: doğru − yanlış/4. LGS: doğru − yanlış/3. Computed when the
            counts are known.
      required:
        - subject
        - label
        - short
        - dogru
        - yanlis
        - bos
        - net
    DenemeTopicResult:
      type: object
      properties:
        subject:
          type: string
          description: >-
            Canonical subject key — exam-prefixed, e.g. `tyt_matematik`,
            `ayt_tarih1`, `lgs_fen`.
        topic:
          type: string
          description: 'Free text: `Paragraf`, `Türev`, …'
        dogru:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        yanlis:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        bos:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
      required:
        - subject
        - topic
        - dogru
        - yanlis
        - bos
    ValidationIssue:
      type: object
      properties:
        path:
          type: string
          description: Dotted path to the offending field, empty at the root.
        message:
          type: string
      required:
        - path
        - message
  securitySchemes:
    supabaseJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Supabase access token: `Authorization: Bearer <token>`'

````

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