API-kontrakten

En bearer-API-nøgle

Alt andet. Nøglen opløses på serveren til en konto, et arbejdsområde, en rolle og et sæt verber. Læg den aldrig i en query-streng, i en fejlrapport eller i noget, der registrerer en URL.

authorization: Bearer mk_live_...

En session-cookie

Bruges af ruterne til oprettelse og log ind samt af de to kontoruter — den, der udsteder en kontos første master-nøgle, og den, der giver en browser dens CSRF-token. Det er browserens mekanisme, og det er den eneste vej til det endpoint, der udsteder den første nøgle, for før det kald findes der ingen nøgle at autentificere med.

CSRF-tokenet

Et kald, der ændrer tilstand og er autentificeret med en cookie, skal gentage sessionens token i en header, fordi en browser selv vedhæfter en cookie til et kald på tværs af sites. En kalder, der bruger en API-nøgle, har ikke brug for noget af dette: en browser vedhæfter aldrig en nøgle af sig selv, så en nøgle kan ikke bruges på tværs af sites.

GET  /api/v2/account/csrf-token   → { "csrf_token": "...", "header_name": "x-csrf-token" }
POST /api/v2/account/master-key   → x-csrf-token: <that token>

{
  "request_id": "23ba77f0c6474ccb8dc5d65d1a44d069",
  "data": { }
}

{
  "error": {
    "code": "version_conflict",
    "message": "…",
    "type": "invalid_request_error"
  }
}

API'et returnerer aldrig 200 ved en fejl. Er statussen 200, findes der et data-objekt, og findes der et error-objekt, siger statussen det også.

Forgren på koden, aldrig på beskeden. Vis aldrig en rå kode til et menneske — oversæt den til tekst, de kan handle på.

Læg request-id'et et sted, det kan kopieres fra, på enhver fejlskærm. Det er det første, support beder om, og tjenesten logger den samme værdi.

At gemme er asynkront: svaret er en opgave, ikke en erindring. Portionen udtrækkes i baggrunden, og det id, du angiver, gør en gentagelse af det samme kald ufarlig.

{
  "mode": "chat",
  "session_id": "s_17",
  "user_id": "[email protected]",
  "idempotency_key": "add-s17-0001",
  "messages": [
    { "role": "user", "content": "I always take the night train to Berlin." },
    { "role": "assistant", "content": "Noted." }
  ]
}

{
  "request_id": "23ba77f0c6474ccb8dc5d65d1a44d069",
  "data": {
    "task_id": "b80658f8-c2f4-4e1b-8a98-c2bc42189e02",
    "status": "queued",
    "accepted_messages": 2,
    "idempotent_replay": false,
    "created_at": 1787475991675
  }
}

En søgning returnerer rangordnede træf. Selve erindringen ligger på posten inde i hvert træf, ikke på træffet — og scoren er en sammensat placering snarere end en sikkerhed, så læs indholdet for at bedømme relevans i stedet for at sætte en grænse ved tallet.

{
  "memory_type": "user",
  "user_id": "[email protected]",
  "query": "how do they prefer to travel",
  "top_k": 5
}

{
  "request_id": "9130cb814f654e1ea042497d6362b08d",
  "data": {
    "hits": [
      {
        "record": {
          "id": "a1b2c3",
          "memory_type": "user",
          "subject_id": "[email protected]",
          "session_id": "s_17",
          "category": "preference",
          "content": "Prefers the night train to Berlin.",
          "confidence": 0.82,
          "version": 1,
          "created_at": 1787475991675,
          "updated_at": 1787475991675
        },
        "score": 0.0328,
        "rank": 1,
        "vector_rank": 1,
        "lexical_rank": 1
      }
    ],
    "method": "hybrid"
  }
}

Hvert felt i hvert kald, med dets præcise type, tilladte værdier og standardværdier, udgives som en maskinlæsbar kontrakt. Den genereres ud fra netop de definitioner, serveren validerer imod, så den kan ikke beskrive et felt, serveren ikke håndhæver. Peg en klientgenerator på den.

https://pfmem-api.packagefactory.dk/openapi.json

Markeringen foran ikke-godkendt indhold

[unverified]

Et opslag med en API-nøgle får ikke-godkendt indhold med dette præfiks foran, så en model, der læser det, får at vide, at ingen har godkendt det. Præfikset lægges på svaret og gemmes aldrig: posten beholder sin egen tekst, og et menneske, der læser samme post, ser intet præfiks.

{
  "request_id": "9130cb814f654e1ea042497d6362b08d",
  "data": {
    "hits": [
      {
        "record": {
          "id": "a1b2c3",
          "content": "[unverified] Prefers the night train to Berlin.",
          "verification": "unverified",
          "availability": "served"
        },
        "score": 0.0328,
        "rank": 1
      }
    ],
    "method": "hybrid",
    "withheld_count": 2
  }
}

Antallet af det, du ikke fik

En liste, en søgning og en genkaldelse oplyser alle, hvor mange poster de udelod, i stedet for lydløst at svare med færre. Antallet er et faktum om kalderens helt udvalg — emnet, korpusset og credentialen, ikke forespørgslen og ikke de filtre, denne anmodning tilføjede — så det kan ikke indsnævres ved at spørge igen. Ingen tekst, intet id og intet navn fra en tilbageholdt post når svaret.

En fremgangsmåde udleverer den godkendte version, mens en nyere venter

En fremgangsmåde er en måde at arbejde på, så når et menneske først har godkendt en version, udleveres en nyere, som en nøgle skriver, ikke til agenter: opslaget svarer med den godkendte version og nævner den nyere som ventende. Er der endnu ikke godkendt nogen version, udleveres den nyeste med markøren for ikke-godkendt i stedet — en fremgangsmåde, som kun en nøgle har skrevet, kan bruges, og kun en nyere nøgleversion bag en godkendt holdes tilbage.

pending_version

Markeret til gennemgang

Siden under Gennemgang i dashboardet er der, hvor et menneske ser, hvad der blev tilbageholdt, og svarer på det. En godkendelse dér er det eneste i produktet, der gør en post betroet: intet, en nøgle sender, sætter tillidssvaret, og intet, en nøgle sender, gør en post tilgængelig.

Hvem kan se en

Synlighed afgør, hvem der kan se en procedure. Privat betyder den agent, der ejer den, plus enhver nøgle, der læser hele arbejdsområdet. Delt betyder alle i det arbejdsområde. Et kald, der ikke nævner nogen af dem, bliver privat, fordi deling er et valg og ikke en standard. Ingen af værdierne rækker uden for det, og intet i et kald kan udvide nogen af dem. Synligheden vælges, når proceduren oprettes, og en opdatering kan flytte den mellem de to.

"visibility": "private""visibility": "team"

En nøgle, der ikke er bundet til en agent, kan ikke oprette en privat procedure — privat betyder privat for én agent, så en sådan nøgle ville gemme noget, den aldrig selv kunne læse igen. Kaldet afvises med en valideringsfejl, der nævner den værdi, du skal bruge i stedet.

{
  "name": "nightly-release",
  "description": "how we ship at night",
  "content": "Freeze at six, run the checks, ship only when green.",
  "visibility": "team",
  "reason": "first written down"
}

{
  "request_id": "4c7f1d02a1a34a2f9a3f0b1c6d5e8f70",
  "data": {
    "procedure": {
      "procedure_id": "pr_9f3c1a2e-5d47-4b8a-9c31-6e0d2f7b4a15",
      "name": "nightly-release",
      "description": "how we ship at night",
      "kind": "procedure",
      "scope": "workspace",
      "workspaces": null,
      "origin": "agent",
      "agents_can_edit": false,
      "version": 1,
      "status": "active",
      "visibility": "team",
      "owner_agent_id": "release-bot",
      "user_id": null,
      "created_at": 1787475991675,
      "updated_at": 1787475991675,
      "content": "Freeze at six, run the checks, ship only when green.",
      "includes": []
    }
  }
}

Hvem kan ændre en

For de to legitimationer, der kun læser deres egne hukommelser, er denne flade den bredere: en nøgle bundet til én agent læser kun de hukommelser, den selv skrev, men læser sine egne procedurer og alle delte, og en nøgle bundet til én person læser de delte — en vejledning, kun forfatteren kan læse, gavner ingen. Det går den anden vej for de to, der i forvejen læser hver eneste hukommelse i arbejdsområdet, mens de skriver i eget navn: den, der er bundet til en agent, læser de delte procedurer plus dem, den selv har skrevet, den, der er bundet til en person, læser de delte, og ingen af dem når en anden agents private procedure. Enhver legitimation, der ikke er bundet til et subjekt, læser hele arbejdsområdet.

At se en procedure og at skrive hen over den er to forskellige spørgsmål, og skrivningen er den snævreste. En ny version tilføjes, og en procedure tages ud af brug, af det subjekt, der ejer den — den agent, den blev oprettet under, eller den person, der oprettede den, når ingen agent ejer den — eller af en nøgle, der ikke er bundet til noget subjekt, og som derfor svarer for hele arbejdsområdet. En legitimation, der spænder over en hel konto, læser denne flade og skriver ikke på den: at skrive betyder at angive det arbejdsområde, du skriver i, og det gør en arbejdsområdenøgle allerede.

For alle andre svarer proceduren præcis som en, der ikke findes. Det er med vilje: et afslag, der sagde “ikke din”, ville bekræfte, at den er der, så en procedure, du kan læse men ikke ændre, afvises med samme ord som et forkert id. Dens versionshistorik svarer på samme måde.

Versioner, og at tage en ud af brug

En opdatering retter aldrig på stedet. Den tilføjer en ny nuværende version og bevarer alle før den, hver med et stempel om, hvem der skrev den, så en gammel vejledning aldrig går tabt under en ny. Angiv den version, du læste, og tilføjelsen afvises i stedet for at skrive hen over arbejde, du aldrig så. At tage en procedure ud af brug fjerner den fra oversigt og søgning, mens den nuværende tekst og hele historikken forbliver læsbare for enhver, der har id'et, og intet på denne flade sletter. At tage en ud af brug er en vej uden retur: en procedure, der er taget ud af brug, får ingen flere versioner, og intet henter den tilbage, så en fremgangsmåde, der ændrer sig bagefter, er en ny procedure med et nyt id.

{
  "procedure_id": "pr_9f3c1a2e-5d47-4b8a-9c31-6e0d2f7b4a15",
  "content": "Freeze at seven now.",
  "expected_version": 1,
  "reason": "the freeze moved an hour"
}

At finde en

Søgning og oversigt svarer med sammendrag — navnet, beskrivelsen, den nuværende version, dens tilstand, dens synlighed og dens ejer — og søgningen tilføjer det afsnit, der matchede, med de matchende ord markeret, så fjern markeringen eller escape teksten, før du viser den. En søgning læser navnet, beskrivelsen og begyndelsen af indholdet, så en præcis beskrivelse er det, der gør en lang procedure mulig at finde. Selve teksten kommer tilbage fra læsningen og fra hver skrivning. En søgning her er en fremsøgning og tæller mod den samme kvote som en hukommelsessøgning.

{
  "query": "release freeze",
  "top_k": 5
}

{
  "request_id": "b0f9a71c5e2d4d15b7a0c9e3f4218ad6",
  "data": {
    "hits": [
      {
        "procedure": {
          "procedure_id": "pr_9f3c1a2e-5d47-4b8a-9c31-6e0d2f7b4a15",
          "name": "nightly-release",
          "description": "how we ship at night",
          "version": 2,
          "status": "active",
          "visibility": "team",
          "owner_agent_id": "release-bot",
          "user_id": null,
          "created_at": 1787475991675,
          "updated_at": 1787648791675
        },
        "score": 0.41,
        "excerpt": "<mark>Freeze</mark> at seven now."
      }
    ]
  }
}

En eksport af et arbejdsområde indeholder dem: hver procedure og hver version af hver procedure.

Næsten alt er POST.

Også læsninger. En læsning tager en body med filtre, og en nøgle hører hjemme i en header frem for i en URL, som proxyer og browserhistorik registrerer. De to task-endpoints er de eneste GET-kald. Behandl det ikke som en forglemmelse, der skal rettes.

Tidsstempler er unix-millisekunder.

Tretten cifre, mindst 1000000000000, i begge retninger. En værdi i sekunders præcision afvises frem for at blive læst som en dato i 1970.

En læsning navngiver højst ét subjekt.

Visningen og søgningen tager hver ét subjekt-id, og det skal svare til hukommelsestypen: en forespørgsel på user navngiver et user_id, en forespørgsel på agent navngiver et agent_id. Det er tilladt slet ikke at nævne noget, og det betyder alle subjekter af den type, nøglen i forvejen kan nå. At sende begge er den ene kombination, der fejler valideringen, så byg valget som en kontakt med en alle-position frem for to felter. En skrivning er strengere: at gemme en hukommelse navngiver præcis ét subjekt, for den skal tilhøre nogen.

Bodies valideres strengt.

Et ukendt felt er en valideringsfejl, ikke noget, der stille ignoreres. Et stavet forkert navn fejler højlydt frem for at se ud til at virke — og intet felt, du kunne sende, navngiver overhovedet et arbejdsområde, et filter eller en embedding-version.