openapi: 3.0.3
info:
  title: Arcane Public API
  description: |
    REST API for programmatic access to Arcane. Use a project-scoped API key for authentication
    (create one under Project → API Keys in the Arcane UI).
  version: 1.0.0

servers:
  - url: https://your-arcane-instance.example.com
    description: Your Arcane instance

security:
  - apiKey: []

tags:
  - name: prompts
    description: Prompt management
  - name: datasources
    description: Datasource listing
  - name: traces
    description: Trace search and retrieval
  - name: datasets
    description: Dataset management
  - name: entities
    description: Entity management
  - name: evaluations
    description: Evaluation management
  - name: experiments
    description: Experiment management

paths:
  /api/public/prompts:
    get:
      tags: [prompts]
      summary: List prompts
      operationId: listPrompts
      responses:
        "200":
          description: List of prompts

  /api/public/prompts/{prompt_identifier}:
    get:
      tags: [prompts]
      summary: Get prompt
      operationId: getPrompt
      parameters:
        - name: prompt_identifier
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Prompt
        "404":
          description: Prompt not found

  /api/public/prompts/{prompt_identifier}/versions:
    get:
      tags: [prompts]
      summary: List prompt versions
      operationId: listPromptVersions
      parameters:
        - name: prompt_identifier
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: List of prompt versions

  /api/public/prompts/{prompt_identifier}/latest:
    get:
      tags: [prompts]
      summary: Get latest prompt version
      operationId: getLatestPromptVersion
      parameters:
        - name: prompt_identifier
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Latest prompt version

  /api/public/datasources:
    get:
      tags: [datasources]
      summary: List datasources
      operationId: listDatasources
      responses:
        "200":
          description: List of datasources

  /api/public/datasources/{datasourceId}/traces/search:
    post:
      tags: [traces]
      summary: Search traces
      operationId: searchTraces
      parameters:
        - name: datasourceId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                minDuration:
                  type: number
                  description: Minimum duration in milliseconds
                maxDuration:
                  type: number
                  description: Maximum duration in milliseconds
                start:
                  type: string
                  description: Start time (Unix timestamp or ISO 8601)
                end:
                  type: string
                  description: End time (Unix timestamp or ISO 8601)
                limit:
                  type: integer
                  default: 20
                q:
                  type: string
                  description: Query string (TraceQL or query format)
                serviceName:
                  type: string
                operationName:
                  type: string
                attributes:
                  type: string
                  description: Logfmt-formatted attributes
                filterByAttributeExists:
                  type: array
                  items:
                    type: string
      responses:
        "200":
          description: Trace search results

  /api/public/datasources/{datasourceId}/traces/attributes:
    get:
      tags: [traces]
      summary: Get attribute names
      operationId: getAttributeNames
      parameters:
        - name: datasourceId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: List of attribute names (array of strings)
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

  /api/public/datasources/{datasourceId}/traces/attributes/{attributeName}/values:
    get:
      tags: [traces]
      summary: Get attribute values
      operationId: getAttributeValues
      parameters:
        - name: datasourceId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: attributeName
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: List of attribute values (array of strings)
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

  /api/public/datasources/{datasourceId}/traces/{traceId}:
    get:
      tags: [traces]
      summary: Get trace by ID
      operationId: getTrace
      parameters:
        - name: datasourceId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: traceId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Trace details

  /api/public/datasets:
    get:
      tags: [datasets]
      summary: List datasets
      operationId: listDatasets
      responses:
        "200":
          description: List of datasets

  /api/public/datasets/{datasetId}:
    get:
      tags: [datasets]
      summary: Get dataset (paginated rows)
      operationId: getDataset
      parameters:
        - name: datasetId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: search
          in: query
          schema:
            type: string
        - name: sortBy
          in: query
          schema:
            type: string
        - name: sortOrder
          in: query
          schema:
            type: string
            enum: [asc, desc]
      responses:
        "200":
          description: Dataset with paginated rows

  /api/public/datasets/{datasetId}/rows:
    post:
      tags: [datasets]
      summary: Add row to dataset
      operationId: addDatasetRow
      parameters:
        - name: datasetId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [values]
              properties:
                values:
                  type: array
                  items:
                    type: string
      responses:
        "201":
          description: Created row

  /api/public/entities:
    get:
      tags: [entities]
      summary: List entities
      operationId: listEntities
      responses:
        "200":
          description: List of entities

  /api/public/entities/{id}:
    get:
      tags: [entities]
      summary: Get entity
      operationId: getEntity
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Entity details

  /api/public/evaluations:
    get:
      tags: [evaluations]
      summary: List evaluations
      operationId: listEvaluations
      responses:
        "200":
          description: List of evaluations
    post:
      tags: [evaluations]
      summary: Create evaluation
      operationId: createEvaluation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [evaluationType, evaluationScope, name, scoreIds]
              properties:
                evaluationType:
                  type: string
                  enum: [AUTOMATIC, MANUAL]
                evaluationScope:
                  type: string
                  enum: [DATASET, EXPERIMENT]
                name:
                  type: string
                description:
                  type: string
                scoreIds:
                  type: array
                  items:
                    type: string
                    format: uuid
                datasetId:
                  type: string
                  format: uuid
                  description: Required when evaluationScope is DATASET
                experimentIds:
                  type: array
                  items:
                    type: string
                    format: uuid
                  description: Required when evaluationScope is EXPERIMENT
                metadata:
                  type: object
                scoreMappings:
                  type: object
                ragasModelConfigurationId:
                  type: string
                  format: uuid
      responses:
        "201":
          description: Created evaluation

  /api/public/evaluations/{evaluationId}:
    get:
      tags: [evaluations]
      summary: Get evaluation
      operationId: getEvaluation
      parameters:
        - name: evaluationId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Evaluation details

  /api/public/evaluations/{evaluationId}/results:
    post:
      tags: [evaluations]
      summary: Create evaluation result
      operationId: createEvaluationResult
      parameters:
        - name: evaluationId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [scoreResults]
              properties:
                datasetRowId:
                  type: string
                  format: uuid
                experimentResultId:
                  type: string
                  format: uuid
                scoreResults:
                  type: array
                  items:
                    type: object
                    required: [scoreId, value]
                    properties:
                      scoreId:
                        type: string
                        format: uuid
                      value:
                        type: number
                      reasoning:
                        type: string
      responses:
        "201":
          description: Created evaluation result

  /api/public/evaluations/{evaluationId}/experiments/{experimentId}/scores:
    get:
      tags: [evaluations]
      summary: Get experiment scores
      operationId: getExperimentScores
      parameters:
        - name: evaluationId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: experimentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Experiment scores

  /api/public/evaluations/{evaluationId}/scores/{scoreId}/pending-results:
    get:
      tags: [evaluations]
      summary: List pending score results
      operationId: listPendingScoreResults
      parameters:
        - name: evaluationId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: scoreId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: experimentId
          in: query
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        "200":
          description: Paginated pending score results

  /api/public/evaluations/{evaluationId}/scores/{scoreId}/import-results:
    post:
      tags: [evaluations]
      summary: Import score results
      operationId: importScoreResults
      parameters:
        - name: evaluationId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: scoreId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [results]
              properties:
                results:
                  type: array
                  items:
                    type: object
                    required: [value]
                    properties:
                      datasetRowId:
                        type: string
                        format: uuid
                      experimentResultId:
                        type: string
                        format: uuid
                      value:
                        type: number
                      reasoning:
                        type: string
      responses:
        "201":
          description: Import result

  /api/public/experiments:
    get:
      tags: [experiments]
      summary: List experiments
      operationId: listExperiments
      responses:
        "200":
          description: List of experiments
    post:
      tags: [experiments]
      summary: Create experiment
      operationId: createExperiment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, promptVersionId, datasetId]
              properties:
                name:
                  type: string
                description:
                  type: string
                promptVersionId:
                  type: string
                  format: uuid
                datasetId:
                  type: string
                  format: uuid
                promptInputMappings:
                  type: object
      responses:
        "201":
          description: Created experiment

  /api/public/experiments/{experimentId}:
    get:
      tags: [experiments]
      summary: Get experiment
      operationId: getExperiment
      parameters:
        - name: experimentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Experiment details

  /api/public/experiments/{experimentId}/results:
    get:
      tags: [experiments]
      summary: List experiment results (paginated)
      operationId: listExperimentResults
      parameters:
        - name: experimentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
      responses:
        "200":
          description: Paginated experiment results
    post:
      tags: [experiments]
      summary: Create experiment result
      operationId: createExperimentResult
      parameters:
        - name: experimentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [datasetRowId, result]
              properties:
                datasetRowId:
                  type: string
                  format: uuid
                result:
                  type: string
      responses:
        "201":
          description: Created experiment result

components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: Use HTTP Basic Auth with username `api-key` and API key as password, or `Authorization: ApiKey YOUR_API_KEY`
