openapi: 3.0.3
info:
  title: LODA API v2
  version: "2.0.0"
  description: |
    API for managing, evaluating and submitting LODA programs and integer sequences.
servers:
- url: https://api.loda-lang.org/v2
tags:
- name: Programs
  description: Endpoints related to LODA programs
- name: Sequences
  description: Endpoints related to integer sequences
- name: Stats
  description: Endpoints related to statistics
paths:
  /sequences/{id}:
    get:
      tags: [ Sequences ]
      summary: Get integer sequence details
      description: Retrieve detailed information about an integer sequence, including its terms, references, links, and keywords. Integer sequences with an ID starting with 'A' are from the OEIS.
      parameters:
      - $ref: '#/components/parameters/ID'
      responses:
        '200':
          description: Sequence details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SequenceDetails'
        '404':
          description: Sequence not found
  /sequences/search:
    get:
      tags: [ Sequences ]
      summary: Search integer sequences
      description: Search for integer sequences by name, ID, keywords and other criteria. Supports pagination.
      parameters:
      - $ref: '#/components/parameters/Query'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Skip'
      responses:
        '200':
          description: List of matching integer sequences
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
  /programs/{id}:
    get:
      tags: [ Programs ]
      summary: Get LODA program details
      description: Retrieve detailed information about a LODA program for an integer sequence, including its author and code. The IDs of LODA programs match the IDs of the integer sequences that they compute. In particular, LODA programs for OEIS sequences have IDs starting with 'A'.
      parameters:
      - $ref: '#/components/parameters/ID'
      responses:
        '200':
          description: LODA program details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProgramDetails'
        '404':
          description: Program not found
  /programs/search:
    get:
      tags: [ Programs ]
      summary: Search LODA programs
      description: Search for LODA programs by name, ID, keywords, and other criteria. Supports pagination.
      parameters:
      - $ref: '#/components/parameters/Query'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Skip'
      responses:
        '200':
          description: List of matching LODA programs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
  /programs/eval:
    post:
      tags: [ Programs, Sequences ]
      summary: Evaluate a LODA program
      description: Evaluate a LODA program to generate the corresponding integer sequence. The request body should contain the program code in plain text format. An integer sequence a(n) is generated by subsequently evaluating the program with inputs n=0,1,2,... up to the specified number of terms. If an offset is provided, the evaluation starts from n=offset instead of n=0.
      parameters:
      - $ref: '#/components/parameters/EvalNumTerms'
      - $ref: '#/components/parameters/EvalOffset'
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
              description: LODA program code
            example: |
              mov $1,10
              pow $1,$0
              mov $0,$1
              div $0,9
      responses:
        '200':
          description: Evaluation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvalResult'
        '400':
          description: Bad request, invalid program format, or evaluation error
  /programs/{id}/submit:
    post:
      tags: [ Programs ]
      summary: Submit a new LODA program
      parameters:
      - $ref: '#/components/parameters/ID'
      description: Submit a LODA program in plain text format. The request body should contain the program code as text/plain.
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
              description: LODA program code
            example: |
              mov $2,1
              lpb $0
                sub $0,2
                add $2,$1
                add $1,$2
              lpe
              mul $0,$2
              add $0,$1
      responses:
        '201':
          description: Program submitted successfully
        '400':
          description: Program validation error
  /stats/summary:
    get:
      tags: [ Stats ]
      summary: Get statistics summary
      description: Returns a summary of the number of sequences, programs, and formulas in the database.
      responses:
        '200':
          description: Statistics summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsSummary'
  /stats/submitters:
    get:
      tags: [ Stats ]
      summary: List all submitters
      description: Returns a list of all submitters with their number of submitted programs.
      responses:
        '200':
          description: List of submitters
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Submitter'
components:
  parameters:
    ID:
      name: id
      in: path
      required: true
      description: ID of an integer sequence or a LODA program (e.g. A000045)
      example: A000045
      schema:
        type: string
        pattern: '^[A-Z]\d{1,10}$'
    Query:
      name: q
      in: query
      required: true
      description: Search query (keywords, properties, etc.)
      example: Fibonacci numbers
      schema:
        type: string
    EvalNumTerms:
      name: t
      in: query
      required: false
      description: Number of terms to compute for evaluation requests
      schema:
        type: integer
        minimum: 1
        maximum: 10000
        default: 8
    EvalOffset:
      name: o
      in: query
      required: false
      description: Offset used for evaluation requests. If provided, this overrides the default offset specified in the program (or 0 if not specified).
      schema:
        type: integer
    Limit:
      name: limit
      in: query
      required: false
      description: Maximum number of results to return (pagination limit)
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
    Skip:
      name: skip
      in: query
      required: false
      description: Number of items to skip before starting to collect the result set (pagination offset)
      schema:
        type: integer
        minimum: 0
        default: 0
  schemas:
    IDAndName:
      type: object
      properties:
        id:
          type: string
          pattern: '^[A-Z]\d{1,10}$'
          description: ID of the integer sequence or LODA program
          example: A000045
        name:
          type: string
          description: Name of the integer sequence or LODA program
          example: Fibonacci numbers
    SearchResult:
      type: array
      items:
        $ref: '#/components/schemas/IDAndName'
    Terms:
      type: array
      items:
        type: string
        pattern: '^-?\d+$'
        description: Sequence term encoded as a string to support arbitrary-sized integers
    SequenceDetails:
      allOf:
      - $ref: '#/components/schemas/IDAndName'
      - type: object
        properties:
          terms:
            $ref: '#/components/schemas/Terms'
          keywords:
            type: array
            description: Keywords for this sequence
            items:
              type: string
          oeisRef:
            type: string
            description: Reference to the OEIS entry (if applicable)
            example: https://oeis.org/A000045
            nullable: true
    ProgramDetails:
      allOf:
      - $ref: '#/components/schemas/IDAndName'
      - type: object
        properties:
          code:
            type: string
            description: LODA program code in plain text format
          submitter:
            type: string
            description: Name of the submitter of the program
            nullable: true
          keywords:
            type: array
            description: Keywords for this program
            items:
              type: string
          operations:
            type: array
            description: Operations of the LODA program as an array of strings
            items:
              type: string
    EvalResult:
      type: object
      properties:
        terms:
          $ref: '#/components/schemas/Terms'
    Submitter:
      type: object
      properties:
        name:
          type: string
          description: Name of the submitter
        numPrograms:
          type: integer
          description: Number of programs submitted by this user
    StatsSummary:
      type: object
      properties:
        numSequences:
          type: integer
          description: Number of integer sequences
        numPrograms:
          type: integer
          description: Number of LODA programs
        numFormulas:
          type: integer
          description: Number of formulas
