{
  "openapi": "3.0.4",
  "info": {
    "title": "Atlas API",
    "description": "API voor applicaties en derden. Klik Authorize en voer een tenantgebonden API-key in, niet de beheersleutel. Try it out voert echte requests uit: upsert en delete wijzigen data. Gebruik hiervoor een demotenant. Namespaces volgen momenteel het OrderFlow-formaat; dit is geen volledige Pinecone-implementatie. De documentatie bevat geen klantgegevens. Keys worden niet persistent in de browser opgeslagen.",
    "version": "v1"
  },
  "paths": {
    "/records/namespaces/{ns}/upsert": {
      "post": {
        "tags": [
          "Atlas API"
        ],
        "summary": "Records toevoegen of vervangen",
        "description": "WIJZIGT DATA. Vereist een schrijfsleutel. Eén JSON-object per regel (NDJSON), geen JSON-array. Maximaal 96 records en 2 MiB per request; _id 1–512 tekens, text 1–24000 tekens. Gebruik een demotenant voor tests. Bestaande IDs worden vervangen, zonder gedeeltelijke opslag bij een mislukte batch.",
        "operationId": "UpsertRecords",
        "parameters": [
          {
            "name": "ns",
            "in": "path",
            "description": "Gebruik de exacte namespace uit Koppeling/Collecties of describe_index_stats. Formaat: orderflow-{dev|acc|prd}-{slug}-{tenant-uuid}-{items|business-partners}. Maximaal 240 tekens. De tenant moet actief zijn en op de allowlist van de sleutel staan.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/x-ndjson": {
              "schema": {
                "type": "string"
              },
              "example": "{\"_id\":\"demo-monitor\",\"text\":\"Samsung 27 inch monitor\"}\n{\"_id\":\"demo-mes\",\"text\":\"Stanley mes\"}"
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpsertApiResponse"
                }
              }
            }
          },
          "400": {
            "description": "Ongeldige invoer of namespace; onbekende JSON-velden worden geweigerd."
          },
          "401": {
            "description": "API-key ontbreekt, is ongeldig of ingetrokken."
          },
          "403": {
            "description": "Geen toegang tot deze tenant, tenant uitgeschakeld of geen schrijfrecht."
          },
          "409": {
            "description": "Modelrevisieconflict of bestaand uniek gegeven; niet blind opnieuw proberen."
          },
          "413": {
            "description": "Request te groot (maximaal 2 MiB)."
          },
          "429": {
            "description": "Te veel gelijktijdige requests voor deze sleutel (maximaal 4). Probeer later opnieuw."
          },
          "503": {
            "description": "Database of embeddings tijdelijk niet beschikbaar; probeer later opnieuw."
          },
          "415": {
            "description": "Gebruik Content-Type application/x-ndjson."
          },
          "422": {
            "description": "Tekst overschrijdt de tokenlimiet van het model; geen records gewijzigd."
          },
          "502": {
            "description": "Embeddingservice gaf een lege, onvolledige of ongeldige vector terug; geen records gewijzigd."
          }
        }
      }
    },
    "/records/namespaces/{ns}/search": {
      "post": {
        "tags": [
          "Atlas API"
        ],
        "summary": "Semantisch zoeken",
        "description": "Zoekt uitsluitend binnen de gekozen namespace en de tenantrechten van de sleutel. query.inputs.text: 1–24000 tekens; query.top_k: 1–100 (standaard 10). De score is cosine-overeenkomst, geen kans of AI-confidence. Model-tokenlimieten kunnen kortere invoer vereisen. TEI weigert te lange invoer; voor de optionele gateway moet de beheerder deze garantie bij de gatewaybeheerder bevestigen.",
        "operationId": "SearchRecords",
        "parameters": [
          {
            "name": "ns",
            "in": "path",
            "description": "Gebruik de exacte namespace uit Koppeling/Collecties of describe_index_stats. Formaat: orderflow-{dev|acc|prd}-{slug}-{tenant-uuid}-{items|business-partners}. Maximaal 240 tekens. De tenant moet actief zijn en op de allowlist van de sleutel staan.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              },
              "example": {
                "query": {
                  "inputs": {
                    "text": "Samsung monitor 27 inch"
                  },
                  "top_k": 10
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchApiResponse"
                }
              }
            }
          },
          "400": {
            "description": "Ongeldige invoer of namespace; onbekende JSON-velden worden geweigerd."
          },
          "401": {
            "description": "API-key ontbreekt, is ongeldig of ingetrokken."
          },
          "403": {
            "description": "Geen toegang tot deze tenant, tenant uitgeschakeld of geen schrijfrecht."
          },
          "409": {
            "description": "Modelrevisieconflict of bestaand uniek gegeven; niet blind opnieuw proberen."
          },
          "413": {
            "description": "Request te groot (maximaal 2 MiB)."
          },
          "429": {
            "description": "Te veel gelijktijdige requests voor deze sleutel (maximaal 4). Probeer later opnieuw."
          },
          "503": {
            "description": "Database of embeddings tijdelijk niet beschikbaar; probeer later opnieuw."
          },
          "422": {
            "description": "Tekst overschrijdt de tokenlimiet van het model; geen records gewijzigd."
          },
          "502": {
            "description": "Embeddingservice gaf een lege, onvolledige of ongeldige vector terug; geen records gewijzigd."
          }
        }
      }
    },
    "/vectors/delete": {
      "post": {
        "tags": [
          "Atlas API"
        ],
        "summary": "Records verwijderen",
        "description": "VERWIJDERT DATA. Vereist een schrijfsleutel. Geef 1–1000 expliciete IDs (1–512 tekens) binnen één namespace op. Geen deleteAll. Gebruik een demotenant voor tests. Antwoord is een leeg JSON-object; onbekende IDs worden genegeerd.",
        "operationId": "DeleteRecords",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeleteRequest"
              },
              "example": {
                "namespace": "VUL-HIER-JE-EIGEN-NAMESPACE-IN",
                "ids": [
                  "demo-monitor"
                ]
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "400": {
            "description": "Ongeldige invoer of namespace; onbekende JSON-velden worden geweigerd."
          },
          "401": {
            "description": "API-key ontbreekt, is ongeldig of ingetrokken."
          },
          "403": {
            "description": "Geen toegang tot deze tenant, tenant uitgeschakeld of geen schrijfrecht."
          },
          "409": {
            "description": "Modelrevisieconflict of bestaand uniek gegeven; niet blind opnieuw proberen."
          },
          "413": {
            "description": "Request te groot (maximaal 2 MiB)."
          },
          "429": {
            "description": "Te veel gelijktijdige requests voor deze sleutel (maximaal 4). Probeer later opnieuw."
          },
          "503": {
            "description": "Database of embeddings tijdelijk niet beschikbaar; probeer later opnieuw."
          }
        }
      }
    },
    "/describe_index_stats": {
      "get": {
        "tags": [
          "Atlas API"
        ],
        "summary": "Collecties en aantallen ophalen",
        "description": "Alleen actieve tenants waarvoor de API-key toegang heeft. GET en POST leveren hetzelfde resultaat; geen requestbody nodig.",
        "operationId": "GetIndexStats",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatsApiResponse"
                }
              }
            }
          },
          "400": {
            "description": "Ongeldige invoer of namespace; onbekende JSON-velden worden geweigerd."
          },
          "401": {
            "description": "API-key ontbreekt, is ongeldig of ingetrokken."
          },
          "403": {
            "description": "Geen toegang tot deze tenant, tenant uitgeschakeld of geen schrijfrecht."
          },
          "409": {
            "description": "Modelrevisieconflict of bestaand uniek gegeven; niet blind opnieuw proberen."
          },
          "413": {
            "description": "Request te groot (maximaal 2 MiB)."
          },
          "429": {
            "description": "Te veel gelijktijdige requests voor deze sleutel (maximaal 4). Probeer later opnieuw."
          },
          "503": {
            "description": "Database of embeddings tijdelijk niet beschikbaar; probeer later opnieuw."
          }
        }
      },
      "post": {
        "tags": [
          "Atlas API"
        ],
        "summary": "Collecties en aantallen ophalen",
        "description": "Alleen actieve tenants waarvoor de API-key toegang heeft. GET en POST leveren hetzelfde resultaat; geen requestbody nodig.",
        "operationId": "PostIndexStats",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatsApiResponse"
                }
              }
            }
          },
          "400": {
            "description": "Ongeldige invoer of namespace; onbekende JSON-velden worden geweigerd."
          },
          "401": {
            "description": "API-key ontbreekt, is ongeldig of ingetrokken."
          },
          "403": {
            "description": "Geen toegang tot deze tenant, tenant uitgeschakeld of geen schrijfrecht."
          },
          "409": {
            "description": "Modelrevisieconflict of bestaand uniek gegeven; niet blind opnieuw proberen."
          },
          "413": {
            "description": "Request te groot (maximaal 2 MiB)."
          },
          "429": {
            "description": "Te veel gelijktijdige requests voor deze sleutel (maximaal 4). Probeer later opnieuw."
          },
          "503": {
            "description": "Database of embeddings tijdelijk niet beschikbaar; probeer later opnieuw."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DeleteRequest": {
        "type": "object",
        "properties": {
          "namespace": {
            "type": "string",
            "nullable": true
          },
          "ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "QueryInput": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "SearchApiFields": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "SearchApiHit": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string",
            "nullable": true
          },
          "_score": {
            "type": "number",
            "format": "double"
          },
          "fields": {
            "$ref": "#/components/schemas/SearchApiFields"
          }
        },
        "additionalProperties": false
      },
      "SearchApiMetrics": {
        "type": "object",
        "properties": {
          "latencyMs": {
            "type": "integer",
            "format": "int64"
          },
          "model": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "SearchApiResponse": {
        "type": "object",
        "properties": {
          "result": {
            "$ref": "#/components/schemas/SearchApiResult"
          },
          "namespace": {
            "type": "string",
            "nullable": true
          },
          "atlas": {
            "$ref": "#/components/schemas/SearchApiMetrics"
          }
        },
        "additionalProperties": false
      },
      "SearchApiResult": {
        "type": "object",
        "properties": {
          "hits": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchApiHit"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "SearchQuery": {
        "type": "object",
        "properties": {
          "inputs": {
            "$ref": "#/components/schemas/QueryInput"
          },
          "top_k": {
            "type": "integer",
            "format": "int32"
          }
        },
        "additionalProperties": false
      },
      "SearchRequest": {
        "type": "object",
        "properties": {
          "query": {
            "$ref": "#/components/schemas/SearchQuery"
          }
        },
        "additionalProperties": false
      },
      "StatsApiNamespace": {
        "type": "object",
        "properties": {
          "vectorCount": {
            "type": "integer",
            "format": "int64"
          }
        },
        "additionalProperties": false
      },
      "StatsApiResponse": {
        "type": "object",
        "properties": {
          "namespaces": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/StatsApiNamespace"
            },
            "nullable": true
          },
          "totalVectorCount": {
            "type": "integer",
            "format": "int64"
          },
          "dimension": {
            "type": "integer",
            "format": "int32"
          },
          "metric": {
            "type": "string",
            "nullable": true
          },
          "vectorType": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "UpsertApiResponse": {
        "type": "object",
        "properties": {
          "upsertedCount": {
            "type": "integer",
            "format": "int32"
          }
        },
        "additionalProperties": false
      }
    },
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "description": "Tenantgebonden Atlas API-key. Leessleutels kunnen zoeken/tellen; schrijven vereist canWrite.",
        "name": "Api-Key",
        "in": "header"
      }
    }
  },
  "security": [
    {
      "ApiKey": [ ]
    }
  ],
  "tags": [
    {
      "name": "Atlas API"
    }
  ]
}