{
  "openapi": "3.1.0",
  "info": {
    "title": "EVA API",
    "version": "1.0.0",
    "summary": "AI analysis of expense receipts.",
    "description": "Submit an expense receipt (PDF, JPEG or PNG) to EVA's AI analysis and read the compliance verdict, the extracted data and the result of every check. Analysis is asynchronous: POST /analyses/ returns a status_url to poll until status is no longer `reading` or `analysing`. Reference: https://tevasoft.io/en/developers/api",
    "contact": { "name": "TEVASOFT", "url": "https://tevasoft.io/#contact" },
    "termsOfService": "https://tevasoft.io/agreements"
  },
  "externalDocs": { "description": "EVA API reference", "url": "https://tevasoft.io/en/developers/api" },
  "servers": [
    {
      "url": "https://{workspace}.tevasoft.io/api/v1",
      "description": "Your EVA workspace",
      "variables": {
        "workspace": { "default": "acme", "description": "Name of your EVA workspace, given at onboarding." }
      }
    }
  ],
  "security": [{ "apiKey": [] }],
  "tags": [{ "name": "Categories" }, { "name": "Analyses" }],
  "paths": {
    "/categories/": {
      "get": {
        "tags": ["Categories"],
        "operationId": "listCategories",
        "summary": "List expense categories",
        "description": "Expense categories of the workspace, sorted by name. The category decides the checks applied to an analysis.",
        "responses": {
          "200": {
            "description": "Categories",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["categories"],
                  "properties": {
                    "categories": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/analyses/": {
      "post": {
        "tags": ["Analyses"],
        "operationId": "createAnalysis",
        "summary": "Submit a receipt for analysis",
        "description": "Submits a receipt. The same file for the same employee and category within 10 minutes returns the existing analysis with status 200, without creating a new one.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": { "$ref": "#/components/schemas/AnalysisSubmission" },
              "encoding": { "file": { "contentType": "application/pdf, image/jpeg, image/png" } }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Analysis accepted",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisAccepted" } } }
          },
          "200": {
            "description": "Same receipt already submitted for this employee and category in the last 10 minutes: existing analysis",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisAccepted" } } }
          },
          "400": {
            "description": "Missing or invalid field",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldErrors" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "411": {
            "description": "Missing Content-Length header",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldErrors" } } }
          },
          "413": {
            "description": "Request larger than 15 MB",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldErrors" } } }
          },
          "422": {
            "description": "Employee excluded from EVA analysis",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldErrors" } } }
          },
          "429": {
            "description": "Per-key rate limit (detail) or workspace daily cap (errors.non_field_errors) reached",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/DetailError" },
                    { "$ref": "#/components/schemas/FieldErrors" }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/analyses/{id}/": {
      "get": {
        "tags": ["Analyses"],
        "operationId": "getAnalysis",
        "summary": "Retrieve an analysis",
        "description": "State of an analysis. Poll every 2 to 5 seconds while status is `reading` or `analysing`. verdict, extracted and checks are only present when status is `done`.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
        ],
        "responses": {
          "200": {
            "description": "Analysis",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Analysis" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": {
            "description": "Unknown analysis in this workspace",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldErrors" } } }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "eva_…",
        "description": "API key created in EVA under Config > API access. Shown once; keys do not expire and can be revoked."
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing, invalid or revoked key, or deactivated account",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailError" } } }
      },
      "Forbidden": {
        "description": "API not enabled for the workspace, or user without audit rights on all expenses",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailError" } } }
      },
      "RateLimited": {
        "description": "Rate limit reached: 30 submissions or 300 reads per minute per key",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailError" } } }
      }
    },
    "schemas": {
      "Category": {
        "type": "object",
        "required": ["id", "name", "max_amount"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "name": { "type": "string" },
          "max_amount": { "type": ["number", "null"], "description": "Cap set for the category, null when none." }
        }
      },
      "AnalysisSubmission": {
        "type": "object",
        "required": ["file", "category", "employee_external_id", "employee_first_name", "employee_last_name"],
        "properties": {
          "file": {
            "type": "string",
            "contentMediaType": "application/octet-stream",
            "description": "PDF, JPEG or PNG, 15 MB max, images up to 50 megapixels. The content must match the declared type."
          },
          "category": { "type": "string", "format": "uuid", "description": "Category id from GET /categories/." },
          "employee_external_id": {
            "type": "string",
            "maxLength": 46,
            "description": "Your stable employee identifier. EVA never matches employees by name."
          },
          "employee_first_name": { "type": "string", "maxLength": 255 },
          "employee_last_name": { "type": "string", "maxLength": 255 },
          "employee_email": { "type": "string", "format": "email" }
        }
      },
      "AnalysisAccepted": {
        "type": "object",
        "required": ["id", "status", "status_url"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "status": { "$ref": "#/components/schemas/AnalysisStatus" },
          "status_url": { "type": "string", "format": "uri", "description": "URL to poll with GET." }
        }
      },
      "AnalysisStatus": {
        "type": "string",
        "enum": ["reading", "analysing", "done", "unreadable", "not_applicable", "frozen", "stalled"],
        "description": "reading: OCR in progress. analysing: checks running. done: verdict available. unreadable: receipt could not be read. not_applicable: no check applies. frozen: paused on the EVA side, will resume. stalled: no progress for 15 minutes."
      },
      "Analysis": {
        "type": "object",
        "required": ["id", "status", "category", "created_at", "web_url"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "status": { "$ref": "#/components/schemas/AnalysisStatus" },
          "category": { "type": ["string", "null"] },
          "created_at": { "type": "string", "format": "date-time" },
          "web_url": { "type": "string", "format": "uri", "description": "Expense report in EVA, for a signed-in auditor." },
          "verdict": {
            "type": "string",
            "enum": ["passed", "failed", "manual_review"],
            "description": "Only when status is done."
          },
          "extracted": { "$ref": "#/components/schemas/ExtractedData" },
          "checks": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/CheckResult" },
            "description": "Only when status is done. Anomalies first."
          }
        }
      },
      "ExtractedData": {
        "type": "object",
        "description": "Data read on the receipt. Only when status is done.",
        "properties": {
          "total_amount": { "type": ["number", "null"] },
          "currency": { "type": ["string", "null"], "description": "ISO 4217 code." },
          "invoice_date": { "type": ["string", "null"], "format": "date" },
          "establishment": { "type": ["string", "null"] },
          "invoice_number": { "type": ["string", "null"] },
          "document_type": { "type": ["string", "null"] }
        }
      },
      "CheckResult": {
        "type": "object",
        "required": ["code", "label", "passed", "severity", "error_code", "message", "warning"],
        "properties": {
          "code": { "type": "string", "description": "Stable check identifier, e.g. duplicate_check." },
          "label": { "type": "string" },
          "passed": { "type": "boolean" },
          "severity": { "type": "string", "enum": ["passed", "failed", "manual_review"] },
          "error_code": { "type": ["string", "null"] },
          "message": { "type": "string", "description": "Human-readable explanation, empty when passed." },
          "warning": { "type": "string" }
        }
      },
      "DetailError": {
        "type": "object",
        "required": ["detail"],
        "properties": { "detail": { "type": "string" } }
      },
      "FieldErrors": {
        "type": "object",
        "required": ["errors"],
        "properties": {
          "errors": {
            "type": "object",
            "description": "Field name (or non_field_errors) to list of messages.",
            "additionalProperties": { "type": "array", "items": { "type": "string" } }
          }
        }
      }
    }
  }
}
